​
Quick Start: Your First Inference

The easiest way to interact with the APUS AI service is by using our @apus/ai Lua library. It handles all the complex messaging and payment details for you, so you can call the AI in a single line of code.

​
Step 1: Get Credits

Before you start, you need Credits to pay for inference requests. During the AO Hackathon, we are providing free credits to all participants.
  1. Join our Discord: [LINK_TO_DISCORD_HERE]
  2. Go to the #hackathon-credits channel.
  3. Post your aos process ID to receive your free credits.

​
Step 2: Load the Library

In your aos terminal, load the @apus/ai library into your process. We recommend using a package manager like apm. If you don’t have it, first run .load-blueprint apm. 
-- Install the library using apm
.load-blueprint apm
apm.install("@apus/ai")
 
-- Require the library in your code
ApusAI = require('@apus/ai')

​
Step 3: Run Your First Prompt

Now you can call the AI. The library will handle the rest. 
ApusAI.infer("What is the weather?")
After a few moments, you will see the AI’s response printed in your terminal. Congratulations, you’ve just performed your first GPU-accelerated AI inference on AO!

​
Using the @apus/ai Lua Library

While the Quick Start showed you the simplest way to get a response, the @apus/ai library offers more control over the inference process through advanced options and callbacks.

​
Setup

First, ensure the library is loaded in your aos process. 
APM.install("@apus/ai")
ApusAI = require("@apus/ai")

​
Core Functions

The library provides a clean, simple interface for all interactions with the APUS AI service.

​
ApusAI.infer(prompt, options, callback)

This is the primary function for sending an inference request. It’s designed to be flexible, supporting both simple fire-and-forget calls and more complex, stateful interactions. Parameters:
  • prompt (string): Required. The text prompt you want to send to the AI model.
  • options (table): Optional. A table of parameters to customize the inference request.
    • session (string): An existing session ID to continue a previous conversation. If a session ID is not provided, a new one will be created for the first turn.
    • reference (string): A custom unique ID for your request. If omitted, the library generates one automatically. This is useful for tracking your requests.
    • …(and any other runtime parameter like temperature, max_tokens, etc.)
  • callback(err, res) (function): Optional. A function that will be called with the result.
    • If err is present, it will be a table containing error details (e.g., { message = "Insufficient credits" }).
    • If successful, res will be a table containing the response: 
      {
  data = "The AI's text response.",
  session = "The-session-id-for-this-conversation",
  attestation = "The-gpu-attestation-string",
  reference = "The-unique-request-reference"
}
    • If no callback is provided, the response or error is printed directly to the console.
Returns:
  • string: The unique reference ID for the request, which can be used for tracking.
Examples:
  1. Simple prompt (like Quick Start): 
    ApusAI.infer("What is Arweave?")
  2. Using a callback to handle the response programmatically: 
    local prompt = "Translate 'hello world' to French."

ApusAI.infer(prompt, nil, function(err, res)
    if err then
        print("Error: " .. err.message)
        return
    end
    print("French Translation: " .. res.data)
    -- You could now store res.session to continue this conversation
end)
  3. Advanced call with runtime options and a session: 
    -- Assume `currentSessionId` was saved from a previous response
local options = {
    session = currentSessionId,
    temperature = 0.8,
    max_tokens = 250
}

ApusAI.infer("Tell me more about that.", options, function(err, res)
  if err then print(err.message) return end

  print("Follow-up response: " .. res.data)
  -- Save the new session ID if it has changed
  currentSessionId = res.session
end)

​
ApusAI.setRouter(routerProcess)

Overrides the default Router Process ID. Useful for testing or if the main router process changes. Parameters:
  • routerProcess (string): The new AO Process ID to use as the router.
Example: 
-- Only needed if you want to use a different router
ApusAI.setRouter("ANOTHER_ROUTER_PROCESS_ID")