The Algorithmia Ruby Client
The Algorithmia Ruby client is a wrapper for making calls to the Algorithmia API and Data API.
With Algorithmia, you can leverage algorithms written in any language by including them in your Ruby project with a simple API call! Browse the collection of algorithms available on Algorithmia.com.
Getting started
The Algorithmia ruby client is available on rubygems.
Simply add gem 'algorithmia'
to your application's Gemfile and run bundle install
.
Then create an Algorithmia client and authenticate with your API key:
require 'algorithmia'
client = Algorithmia.client('YOUR_API_KEY')
You are now ready to call algorithms.
Calling algorithms
The following examples of calling algorithms are organized by type of input/output which vary between algorithms.
Note: a single algorithm may have different input and output types, or accept multiple types of input, so consult the algorithm's description for usage examples specific to that algorithm.
Text input/output
Call an algorithm with text input by simply passing a string into its pipe
method.
If the algorithm output is text, then the result field of the response will be a string.
algo = client.algo('demo/Hello/0.1.1')
puts algo.pipe('HAL 9000').result
# -> Hello HAL 900
JSON input/output
Call an algorithm with JSON input by simply passing in a type that can be serialized to JSON, like an Array
or Hash
.
For algorithms that return JSON, the result field of the response will be the appropriate deserialized type.
algo = client.algo('WebPredict/ListAnagrams/0.1.0')
result = algo.pipe(["transformer", "terraforms", "retransform"]).result
# -> ["transformer","retransform"]
Alternatively, if your input is already serialized to JSON, you may call pipe_json
:
algo = client.algo('WebPredict/ListAnagrams/0.1.0')
result = algo.pipe_json('["transformer", "terraforms", "retransform"]').result
# -> ["transformer","retransform"]
Binary input/output
Call an algorithm with Binary input by passing an ASCII-8BIT
-encoded string into the pipe
method.
Similarly, if the algorithm response is binary data, then the result field of the response will be an ASCII-8BIT
string.
In practice, this involves working with methods like IO.binread
and IO.binwrite
.
input = File.binread("/path/to/bender.png")
result = client.algo("opencv/SmartThumbnail/0.1").pipe(input).result
# -> [ASCII-8BIT string of binary data]
Error handling
API errors and Algorithm exceptions will be raised when calling pipe
:
client.algo('util/whoopsWrongAlgo').pipe('Hello, world!')
# -> Algorithmia::Errors::NotFoundError: algorithm algo://util/whoopsWrongAlgo not found
And you can rescue Algorithm errors separate from other errors:
begin
client.algo('demo/Hello').pipe('world!')
rescue Algorithmia::Errors::AlgorithmError => e
puts "Algorithm Error: #{e.message}"
puts e.stacktrace
rescue => e
puts "Error: #{e.message}"
end
Request options
The client exposes options that can configure algorithm requests. This includes support for changing the timeout or indicating that the API should include stdout in the response.
algo = client.algo('demo/Hello/0.1.1').set(timeout: 10, stdout: true)
response = algo.pipe('HAL 9000')
stdout = response.stdout
Note: stdout: true
is ignored if you do not have access to the algorithm source.
Working with data
The Algorithmia Java client also provides a way to manage both Algorithmia hosted data and data from Dropbox or S3 accounts that you've connected to you Algorithmia account.
This client provides a DataFile
type (generally created by client.file(uri)
)
and a DataDir
type (generally created by client.dir(uri)
) that provide methods for managing your data.
Create directories
Create directories by instantiating a DataDirectory
object and calling create
:
client.dir("data://.my/robots").create
client.dir("dropbox://robots").create
Upload files to a directory
Upload files by calling put
on a DataFile
object, or by calling putFile
on a DataDirectory
object.
robots = client.dir("data://.my/robots")
# Upload local file
robots.put_file("/path/to/Optimus_Prime.png")
# Write a text file
robots.file("Optimus_Prime.txt").put("Leader of the Autobots")
# Write a binary file
robots.file("Optimus_Prime.key").put([71, 101, 101, 107].pack('C*'))
Download contents of file
Download files by calling get
or get_file
on a DataFile
object:
# Download file and get the file handle
t800File = client.file("data://.my/robots/T-800.png").get_file
# Get file's contents as a string
t800Text = client.file("data://.my/robots/T-800.txt").get
# Get file's contents as JSON
t800JsonString = client.file("data://.my/robots/T-800.txt").get
t800Json = JSON.parse(t800JsonString)
# Get file's contents as a byte array
t800Bytes = client.file("data://.my/robots/T-800.png").get
Delete files and directories
Delete files and directories by calling delete on their respective DataFile
or DataDirectory
object.
DataDirectories take an optional force
parameter that indicates whether the directory should be deleted
if it contains files or other directories.
client.file("data://.my/robots/C-3PO.txt").delete
client.dir("data://.my/robots").delete(false)
List directory contents
Iterate over the contents of a directory using the iterated returned
by calling each
, each_directory
, or each_file
on a DataDirectory
object.
If no block is given to the method, an enumerator will be returned.
# List top level directories
client.dir("data://.my").each_dir do |dir|
puts "Directory " + dir.data_uri
end
# List files in the 'robots' directory
client.dir("data://.my/robots").each_file do |file|
puts "File " + file.data_uri
end
# Iterate all directory contents
client.dir("dropbox://").each do |item|
puts file.data_uri
end
Development
After 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.
Contributing
Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.