A simple, lightweight Ruby client for the Ollama API.
Add this line to your application's Gemfile:
gem'smollama'And then execute:
$ bundle install
Or install it yourself as:
$ gem install smollama
Configure the client at application startup:
require'smollama'Smollama::Client.configuredo |config|
config.server_ip='127.0.0.1'# 192.168.0.x or similar if you're running Ollama in a box in your LANconfig.server_port=11434# optional, defaults to 11434config.default_model='gpt-oss'endclient=Smollama::Client.newresponse=client.ask("Hello, how are you?")putsresponse[:content]response=client.chat("Explain quantum computing",temperature: 0.6,# NOTE: use 0.2 for coding taskstop_p: 0.98,max_tokens: 500)putsresponse[:content]client.chat("Tell me a story",stream: true)do |chunk|
printchunk['message']['content']ifchunk['message']endmessages=[{role: 'system',content: 'You are a helpful assistant.'},{role: 'user',content: 'What is Ruby?'},{role: 'assistant',content: 'Ruby is a dynamic programming language.'},{role: 'user',content: 'What makes it special?'}]response=client.chat_with_history(messages,temperature: 0.8)putsresponse[:content]# Use a different model for a specific clientspecial_client=Smollama::Client.new(model: 'llama2')response=special_client.ask("Hello!")Vision models can accept images alongside text to describe, classify, and answer questions about what they see.
# Use a vision-capable modelclient=Smollama::Client.new(model: 'gemma3')# With a local file pathresponse=client.chat("What is in this image?",images: ["./cat.jpg"])putsresponse[:content]# With a URLresponse=client.chat("Describe this image",images: ["https://example.com/image.jpg"])# With multiple imagesresponse=client.chat("Compare these images",images: ["./image1.jpg","./image2.jpg"])# With base64 encoded image dataimg_data=Base64.strict_encode64(File.read("./image.jpg"))response=client.chat("What do you see?",images: [img_data])The images parameter accepts:
- File paths (e.g.,
"./image.jpg") - URLs (e.g.,
"https://example.com/image.jpg") - Base64 encoded strings
- An array of any combination of the above
ifclient.pingputs"Ollama server is reachable"elseputs"Cannot reach Ollama server"endmodels=client.list_modelsputs"Available models: #{models['models'].map{ |m| m['name']}.join(', ')}"server_ip: The IP address of your Ollama server (required)server_port: The port number (optional, defaults to 11434)default_model: The default model to use for all clients
temperature: Controls randomness (0.0 to 1.0)top_p: Controls nucleus sampling (0.0 to 1.0)max_tokens: Maximum number of tokens to generatestream: Enable streaming responses (boolean)
Non-streaming responses return a hash with:
:content- The generated text:model- Model used:created_at- Timestamp:total_duration- Total processing time:eval_count- Number of tokens evaluated:eval_duration- Evaluation time
The client gracefully handles errors and returns error information in the response:
response=client.ask("Hello")ifresponse[:error]puts"Error: #{response[:error]}"elseputsresponse[:content]endAfter 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 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 tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/makevoid/smollama.
The gem is available as open source under the terms of the MIT License.