Maritaca AI
A Ruby gem for interacting with MariTalk from Maritaca AI.
This Gem is designed to provide low-level access to MariTalk, enabling people to build abstractions on top of it. If you are interested in more high-level abstractions or more user-friendly tools, you may want to consider Nano Bots 💎 🤖.
TL;DR and Quick Start
gem 'maritaca-ai', '~> 1.1.0'require 'maritaca-ai'
client = Maritaca.new(
credentials: { api_key: ENV['MARITACA_API_KEY'] }
)
result = client.chat_inference(
{ model: 'maritalk',
chat_mode: true,
messages: [ { role: 'user', content: 'Oi!' } ] }
)Result:
{ 'answer' => 'Oi! Como posso ajudá-lo(a) hoje?' }Index
- TL;DR and Quick Start
- Index
- Setup
- Installing
- Credentials
- Usage
- Client
- Custom Address
- Methods
- chat_inference
- Chat
- Back-and-Forth Conversations
- Without Chat
- chat_inference
- New Functionalities and APIs
- Request Options
- Adapter
- Timeout
- Error Handling
- Rescuing
- For Short
- Errors
- Client
- Development
- Purpose
- Publish to RubyGems
- Updating the README
- Resources and References
- Disclaimer
Setup
Installing
gem install maritaca-ai -v 1.1.0gem 'maritaca-ai', '~> 1.1.0'Credentials
You can obtain your API key at MariTalk.
Enclose credentials in single quotes when using environment variables to prevent issues with the $ character in the API key:
MARITACA_API_KEY='123...$a12...'Usage
Client
Ensure that you have an API Key for authentication.
Create a new client:
require 'maritaca-ai'
client = Maritaca.new(
credentials: { api_key: ENV['MARITACA_API_KEY'] }
)Custom Address
You can use a custom address:
require 'maritaca-ai'
client = Maritaca.new(
credentials: {
address: 'https://chat.maritaca.ai',
api_key: ENV['MARITACA_API_KEY']
}
)Methods
chat_inference
Chat
result = client.chat_inference(
{ model: 'maritalk',
chat_mode: true,
messages: [ { role: 'user', content: 'Oi!' } ] }
)Result:
{ 'answer' => 'Oi! Como posso ajudá-lo(a) hoje?' }Back-and-Forth Conversations
To maintain a back-and-forth conversation, you need to append the received responses and build a history for your requests:
result = client.chat_inference(
{ model: 'maritalk',
chat_mode: true,
messages: [
{ role: 'user', content: 'Oi, meu nome é Tamanduá.' },
{ role: 'assistant', content: 'Oi Tamanduá, como posso ajudá-lo hoje?' },
{ role: 'user', content: 'Qual é o meu nome?' }
] }
)Result:
{ 'answer' => 'Seu nome é Tamanduá.' }Without Chat
You can prompt the model without using chat mode:
result = client.chat_inference(
{ model: 'maritalk',
chat_mode: false,
messages: "Minha terra tem palmeiras,\nOnde canta o Sabiá;\n" }
)Result:
{ 'answer' =>
"As aves, que aqui gorjeiam,\n" \
'Não gorjeiam como lá.' }New Functionalities and APIs
Maritaca may launch a new endpoint that we haven't covered in the Gem yet. If that's the case, you may still be able to use it through the request method. For example, chat_inference is just a wrapper for api/chat/inference, which you can call directly like this:
result = client.request(
'api/chat/inference',
{ model: 'maritalk',
chat_mode: true,
messages: [{ role: 'user', content: 'Oi!' }] },
request_method: 'POST'
)Request Options
Adapter
The gem uses Faraday with the Typhoeus adapter by default.
You can use a different adapter if you want:
require 'faraday/net_http'
client = Maritaca.new(
credentials: { api_key: ENV['MARITACA_API_KEY'] },
options: { connection: { adapter: :net_http } }
)Timeout
You can set the maximum number of seconds to wait for the request to complete with the timeout option:
client = Maritaca.new(
credentials: { api_key: ENV['MARITACA_API_KEY'] },
options: { connection: { request: { timeout: 5 } } }
)You can also have more fine-grained control over Faraday's Request Options if you prefer:
client = Maritaca.new(
credentials: { api_key: ENV['MARITACA_API_KEY'] },
options: {
connection: {
request: {
timeout: 5,
open_timeout: 5,
read_timeout: 5,
write_timeout: 5
}
}
}
)Error Handling
Rescuing
require 'maritaca-ai'
begin
client.chat_inference(
{ model: 'maritalk',
chat_mode: true,
messages: [ { role: 'user', content: 'Oi!' } ] }
)
rescue Maritaca::Errors::MaritacaError => error
puts error.class # Maritaca::Errors::RequestError
puts error.message # 'the server responded with status 500'
puts error.payload
# { model: 'maritalk',
# chat_mode: true,
# ...
# }
puts error.request
# #<Faraday::ServerError response={:status=>500, :headers...
endFor Short
require 'maritaca-ai/errors'
begin
client.chat_inference(
{ model: 'maritalk',
chat_mode: true,
messages: [ { role: 'user', content: 'Oi!' } ] }
)
rescue MaritacaError => error
puts error.class # Maritaca::Errors::RequestError
endErrors
MaritacaError
MissingAPIKeyError
RequestErrorDevelopment
bundle
rubocop -A
bundle exec ruby spec/tasks/run-client.rbPurpose
This Gem is designed to provide low-level access to MariTalk, enabling people to build abstractions on top of it. If you are interested in more high-level abstractions or more user-friendly tools, you may want to consider Nano Bots 💎 🤖.
Publish to RubyGems
gem build maritaca-ai.gemspec
gem signin
gem push maritaca-ai-1.1.0.gemUpdating the README
Install Babashka:
curl -s https://raw.githubusercontent.com/babashka/babashka/master/install | sudo bashUpdate the template.md file and then:
bb tasks/generate-readme.cljTrick for automatically updating the README.md when template.md changes:
sudo pacman -S inotify-tools # Arch / Manjaro
sudo apt-get install inotify-tools # Debian / Ubuntu / Raspberry Pi OS
sudo dnf install inotify-tools # Fedora / CentOS / RHEL
while inotifywait -e modify template.md; do bb tasks/generate-readme.clj; doneTrick for Markdown Live Preview:
pip install -U markdown_live_preview
mlp README.md -p 8076Resources and References
These resources and references may be useful throughout your learning process.
Disclaimer
This is not an official Maritaca AI project, nor is it affiliated with Maritaca AI in any way.
This software is distributed under the MIT License. This license includes a disclaimer of warranty. Moreover, the authors assume no responsibility for any damage or costs that may result from using this project. Use the Maritaca AI Ruby Gem at your own risk.