The all-in-one Ruby framework for building AI-powered applications and agents.
- Ruby 3.3, 3.4, or 4.0
Install the released gem:
gem install rifferOr add to your application's Gemfile:
gem 'riffer'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')Comprehensive guides live at riffer.ai:
- Overview - Core concepts and architecture
- Getting Started - Installation and first steps
- Agents - Defining and configuring agents
- Agent Lifecycle - Generate, stream, and responses
- Agent Loop - Tool execution flow and stopping
- Tools - Creating tools for agents
- Advanced Tools - Timeouts, runtime, and registration
- Messages - Message types and formats
- Stream Events - Streaming responses
- Configuration - Framework configuration
- Evals - Evaluating agent quality
- Guardrails - Input/output validation
- Skills - Packaged agent capabilities
- MCP - Integrating third-party MCP servers
- Serialization - Persisting and transferring agent definitions
- Tracing - OpenTelemetry span contract and host wiring
- Stability - What's safe to depend on and how upgrades work
- Providers - LLM provider adapters
The guide sources are in the docs directory.
The full API reference is published at riffer.ai/api. Preview the site locally with:
bin/rake docs:serveThen 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.
After checking out the repo, run:
bin/setupCommon 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).
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-projectThe 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.rbGoogle 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.
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.
- 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.
All notable changes to this project are documented in CHANGELOG.md. Breaking releases come with an upgrade guide in UPGRADING.md.
Licensed under the MIT License. See LICENSE.txt for details.