Kotlin SDK

export HINOW_API_KEY="hi_sua_chave_aqui"

import ai.hinow.ChatCompletionRequest
import ai.hinow.Hinow
import ai.hinow.Message
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    // With no arguments, the client reads the key from HINOW_API_KEY.
    // use { } closes the HTTP client when the block ends.
    Hinow().use { client ->
        val answer = client.chat.completions.create(
            ChatCompletionRequest(
                model = "hinow/himax",
                messages = listOf(
                    Message.system("You answer in English."),
                    Message.user("What is an API? Answer in one paragraph."),
                ),
            )
        )

        println(answer.choices[0].message.text)

        val uso = answer.usage
        println("\ninput: ${uso?.promptTokens} · output: ${uso?.completionTokens}")
    }
}

import ai.hinow.ChatCompletionRequest
import ai.hinow.Hinow
import ai.hinow.Message
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    Hinow().use { client ->
        client.chat.completions.createStream(
            ChatCompletionRequest(
                model = "hinow/hinova",
                messages = listOf(Message.user("Write three lines about the sea at dawn.")),
            )
        ) { chunk ->
            // Note the delta: each chunk carries the new fragment, not the whole answer.
            print(chunk.choices.firstOrNull()?.delta?.content ?: "")
        }

        println()
    }
}

import ai.hinow.Hinow
import ai.hinow.SearchType
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    Hinow().use { client ->
        // Answers on the spot: there is no job to follow.
        val search = client.tools.search(
            query = "best beaches in northeast Brazil",
            type = SearchType.SEARCH,
            country = "br",
            lang = "pt-br",
        )

        search.results.forEach { item ->
            println("${item.position}. ${item.title}")
            println("   ${item.url}")
        }

        println("\n${search.results.size} results · US$ ${search.cost}")
    }
}

import ai.hinow.Hinow
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    Hinow().use { client ->
        // The crawl takes a while, so it runs as a job. This method waits for you.
        val job = client.tools.websiteContactsAndWait(
            websites = listOf("https://www.teclia.com"),
            maxDepth = 2,
            maxLinksPerPage = 10,
        )

        val cache = if (job.cached == true) " (from cache)" else ""
        println("status: ${job.status} · US$ ${job.cost}$cache\n")

        // Each item carries the type, the value and the exact page it was found on.
        job.result?.items?.forEach { item ->
            when (item.type) {
                "email", "phone" -> {
                    println(item.type.padEnd(9) + item.value)
                    println("".padEnd(9) + "em ${item.sourceUrl}")
                }
                else -> println((item.platform ?: "").padEnd(9) + (item.url ?: ""))
            }
        }
    }
}

import ai.hinow.*
import kotlinx.coroutines.runBlocking
import kotlinx.serialization.json.*

// Your real function: a when here, just for the example.
fun getOrder(code: String): String = when (code) {
    "A-1001" -> """{"status":"delivered","delivered":"2026-08-02"}"""
    "A-1002" -> """{"status":"in transit","estimated":"2026-08-12"}"""
    else -> """{"error":"order not found"}"""
}

fun main(): Unit = runBlocking {
    Hinow().use { client ->
        // The argument schema, in JSON Schema.
        val schema = buildJsonObject {
            put("type", "object")
            putJsonObject("properties") {
                putJsonObject("code") {
                    put("type", "string")
                    put("description", "Order code, e.g. A-1001")
                }
            }
            putJsonArray("required") { add("code") }
        }

        // 1. The assistant: model, instructions and the functions it may call.
        val assistant = client.beta.assistants.create(
            AssistantRequest(
                model = "hinow/himax",
                name = "Support",
                instructions = "You answer questions about orders. " +
                    "Check the tool before stating any status.",
                tools = listOf(
                    Tool.function(
                        "get_order",
                        "Look up an order by its code.",
                        schema,
                    )
                ),
            )
        )

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

        // 3. Run it and wait.
        var run = client.beta.threads.runs.createAndPoll(thread.id, assistant.id)

        // 4. While the model asks for functions, run them and hand the result back.
        while (run.status == "requires_action") {
            val outputs = run.requiredAction?.submitToolOutputs?.toolCalls.orEmpty().map { call ->
                val args = Json.parseToJsonElement(call.function.arguments).jsonObject
                val code = args["code"]?.jsonPrimitive?.content ?: ""
                println("-> the model called ${call.function.name}($code)")

                ToolOutput(call.id, getOrder(code))
            }

            client.beta.threads.runs.submitToolOutputs(thread.id, run.id, outputs)
            run = client.beta.threads.runs.poll(thread.id, run.id)
        }

        // 5. The final answer is the last message on the thread.
        val messages = client.beta.threads.messages.list(thread.id, limit = 1, order = "desc")
        println("\n${messages.data[0].text}")

        client.beta.assistants.delete(assistant.id)
    }
}

import ai.hinow.Hinow
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    Hinow().use { client ->
        // 1. Upload the document.
        val file = client.files.create("returns-policy.txt")
        println("file: ${file.id} (${file.bytes} bytes)")

        // 2. Create the store and attach the file to it.
        val base = client.vectorStores.create("Support base")
        client.vectorStores.files.create(base.id, file.id)
        println("store: ${base.id}")

        // 3. Indexing is asynchronous. Searching before it finishes returns nothing
        //    at all, with no error, so poll waits for it.
        val state = client.vectorStores.files.poll(base.id, file.id)
        println("indexing: ${state.status}\n")

        // 4. Search by meaning, not by exact word.
        val hits = client.rag.search(
            query = "How many days do I have to return an item?",
            ragId = base.id,
            topK = 3,
        )

        hits.results.forEach { achado ->
            val excerpt = achado.text.replace("\n", " ").take(110)
            println("%.2f  %s".format(achado.score, achado.source))
            println("      $excerpt…")
        }
    }
}

import ai.hinow.*
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    Hinow().use { client ->
        try {
            client.chat.completions.create(
                ChatCompletionRequest(
                    model = "himax", // the hinow/ prefix is missing
                    messages = listOf(Message.user("Olá")),
                )
            )
        } catch (e: AuthenticationException) {
            println("Invalid or expired key. Check HINOW_API_KEY.")
        } catch (e: NotFoundException) {
            println("Not found: ${e.message}")
        } catch (e: InvalidRequestException) {
            println("Invalid request: ${e.message}")
        } catch (e: RateLimitException) {
            println("Rate limited. The SDK already retried; wait a moment.")
        } catch (e: ConnectionException) {
            // Nothing reached the API, so nothing was charged.
            println("Sem answer da API: ${e.message}")
        } catch (e: HinowException) {
            // Safety net: any other error the API reported.
            println("Error ${e.statusCode}: ${e.message}")
        }
    }
}

import ai.hinow.Hinow
import kotlinx.coroutines.runBlocking

fun main(): Unit = runBlocking {
    Hinow().use { client ->
        // Account credit, in US dollars.
        val balance = client.getBalance()
        println("balance: US$ %.2f\n".format(balance.balance))

        // One specific model. The id is namespaced: hinow/himax, not himax.
        val model = client.models.retrieve("hinow/himax")
        println("${model.name} (${model.id})")
        println("categories: ${model.category.joinToString(", ")}")
        println("price per million tokens: input US$ ${model.cost?.input} · output US$ ${model.cost?.output}")
    }
}

val client = Hinow(
    apiKey = System.getenv("HINOW_API_KEY"),  // ou deixe em branco e use a variável
    baseUrl = "https://api.hinow.ai",         // ou HINOW_BASE_URL
    timeout = 120_000,                        // milissegundos
    maxRetries = 2,                           // repete 429 e 5xx
)