Ruby SDK

export HINOW_API_KEY="hi_sua_chave_aqui"

require "hinow"

# With no arguments, the client reads the key from HINOW_API_KEY.
client = Hinow::Client.new

answer = client.chat.completions.create(
  model: "hinow/himax",
  messages: [
    { role: "system", content: "You answer in English." },
    { role: "user", content: "What is an API? Answer in one paragraph." }
  ]
)

puts answer["choices"][0]["message"]["content"]

# What it cost, in tokens.
uso = answer["usage"]
puts "\ninput: #{uso['prompt_tokens']} · output: #{uso['completion_tokens']}"

require "hinow"

client = Hinow::Client.new

client.chat.completions.create_stream(
  model: "hinow/hinova",
  messages: [{ role: "user", content: "Write three lines about the sea at dawn." }]
) do |chunk|
  # Note the "delta": each chunk carries the new fragment, not the whole answer.
  print chunk.dig("choices", 0, "delta", "content")
  $stdout.flush
end

puts

require "hinow"

client = Hinow::Client.new

# Answers on the spot: there is no job to follow.
search = client.tools.search("best beaches in northeast Brazil", country: "br", lang: "pt-br")

search["results"].each do |item|
  puts "#{item['position']}. #{item['title']}"
  puts "   #{item['url']}"
end

puts "\n#{search['results'].size} results · US$ #{search['cost']}"

require "hinow"

client = Hinow::Client.new

# The crawl takes a while, so it runs as a job. This method waits for you.
job = client.tools.website_contacts_and_wait(
  ["https://www.teclia.com"],
  max_depth: 2,
  max_links_per_page: 10
)

puts "status: #{job['status']} · US$ #{job['cost']}#{job['cached'] ? ' (from cache)' : ''}"
puts

# Each item carries the type, the value and the exact page it was found on.
job["result"]["items"].each do |item|
  case item["type"]
  when "email", "phone"
    puts "#{item['type'].ljust(9)}#{item['value']}"
    puts "#{' '.ljust(9)}em #{item['sourceUrl']}"
  else
    puts "#{item['platform'].to_s.ljust(9)}#{item['url']}"
  end
end

require "hinow"
require "json"

client = Hinow::Client.new

# Your real function: a hash here, just for the example.
ORDERS = {
  "A-1001" => { status: "delivered", delivered: "2026-08-02" },
  "A-1002" => { status: "in transit", estimated: "2026-08-12" }
}.freeze

def get_order(code)
  ORDERS[code] || { error: "order not found" }
end

# 1. The assistant: model, instructions and the functions it may call.
assistant = client.beta.assistants.create(
  model: "hinow/himax",
  name: "Support",
  instructions: "You answer questions about orders. Check the tool before stating any status.",
  tools: [{
    type: "function",
    function: {
      name: "get_order",
      description: "Look up an order by its code.",
      parameters: {
        type: "object",
        properties: {
          code: { type: "string", description: "Order code, e.g. A-1001" }
        },
        required: ["code"]
      }
    }
  }]
)

# 2. The conversation and the question.
thread = client.beta.threads.create
client.beta.threads.messages.create(thread["id"], "Has order A-1002 arrived?")

# 3. Run it and wait.
run = client.beta.threads.runs.create_and_poll(thread["id"], assistant_id: assistant["id"])

# 4. While the model asks for functions, run them and hand the result back.
while run["status"] == "requires_action"
  outputs = run["required_action"]["submit_tool_outputs"]["tool_calls"].map do |call|
    args = JSON.parse(call["function"]["arguments"])
    puts "-> the model called #{call['function']['name']}(#{args['code']})"

    {
      tool_call_id: call["id"],
      output: get_order(args["code"]).to_json
    }
  end

  client.beta.threads.runs.submit_tool_outputs(thread["id"], run["id"], outputs)
  run = client.beta.threads.runs.poll(thread["id"], run["id"])
end

# 5. The final answer is the last message on the thread.
messages = client.beta.threads.messages.list(thread["id"], limit: 1, order: "desc")
puts "\n#{messages['data'][0]['content'][0]['text']['value']}"

client.beta.assistants.delete(assistant["id"])

require "hinow"

client = Hinow::Client.new

# 1. Upload the document.
file = client.files.create("returns-policy.txt")
puts "file: #{file['id']} (#{file['bytes']} bytes)"

# 2. Create the store and attach the file to it.
base = client.vector_stores.create(name: "Support base")
client.vector_stores.files.create(base["id"], file["id"])
puts "store: #{base['id']}"

# 3. Indexing is asynchronous. Searching before it finishes returns nothing
#    at all, with no error, so poll waits for it.
state = client.vector_stores.files.poll(base["id"], file["id"])
puts "indexing: #{state['status']}"

# 4. Search by meaning, not by exact word.
hits = client.rag.search(
  "How many days do I have to return an item?",
  rag_id: base["id"],
  top_k: 3
)

puts
hits["results"].each do |achado|
  puts "#{achado['score'].round(2)}  #{achado['source']}"
  puts "      #{achado['text'].tr("\n", ' ')[0, 110]}…"
end

require "hinow"

client = Hinow::Client.new

begin
  client.chat.completions.create(
    model: "himax",  # the hinow/ prefix is missing
    messages: [{ role: "user", content: "Olá" }]
  )
rescue Hinow::AuthenticationError
  puts "Invalid or expired key. Check HINOW_API_KEY."
rescue Hinow::NotFoundError => e
  puts "Not found: #{e.message}"
rescue Hinow::InvalidRequestError => e
  puts "Invalid request: #{e.message}"
rescue Hinow::RateLimitError
  puts "Rate limited. The SDK already retried; wait a moment."
rescue Hinow::ConnectionError => e
  # Nothing reached the API, so nothing was charged.
  puts "Sem answer da API: #{e.message}"
rescue Hinow::Error => e
  # Safety net: any other error the API reported.
  puts "Error #{e.status_code}: #{e.message}"
end

require "hinow"

client = Hinow::Client.new

# Account credit, in US dollars.
balance = client.get_balance
puts "balance: US$ #{format('%.2f', balance['balance'])}"
puts

# One specific model. The id is namespaced: hinow/himax, not himax.
model = client.models.retrieve("hinow/himax")
puts "#{model['name']} (#{model['id']})"
puts "categories: #{model['category'].join(', ')}"

client = Hinow::Client.new(
  api_key: ENV["HINOW_API_KEY"],    # ou deixe em branco e use a variável
  base_url: "https://api.hinow.ai", # ou HINOW_BASE_URL
  timeout: 120,                     # segundos
  max_retries: 2                    # repete 429 e 5xx
)