Foundation v2.4

Technical
Architectures.

Ravonix provides a unified intelligence layer specifically tuned for the Minecraft ecosystem. Our infrastructure abstracts the complexity of prompt engineering and model fine-tuning, offering a streamlined Java SDK that allows developers to focus on gameplay and narrative.

Every endpoint within Ravonix is pre-grounded with an internal knowledge base containing Minecraft technical specifications, block properties, and world-building logic. This ensures that AI responses are not only creative but technically accurate to the game's mechanics, biomes, and server software standards.

Non-Blocking I/O

The SDK utilizes a dedicated worker pool for all network requests, ensuring your server's main tick loop remains stable and jitter-free during AI inference.

Enterprise Security

Built-in AES-256 encryption and Argon2 verification layers protect your project credentials and secure all data transmitted between your server and our nodes.

Installation

To integrate Ravonix into your Java project, you must first add the SDK as a dependency. We support both Maven and Gradle build systems. Ensure your environment is configured for Java 11 or higher to support our asynchronous networking stack.

<dependency>
    <groupId>com.ravonixapi</groupId>
    <artifactId>ravonix-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Authentication

Every request to the Ravonix API must include a Bearer token in the Authorization header. This token, known as your API Key, is a unique identifier starting with the `Rit_` prefix.

Security Protocol

NEVER embed your API key directly into your compiled plugin code. Use the `config.yml` file or environment variables to inject the key at runtime.

Initialization

The `Ravonix` class acts as the centralized gateway for the entire SDK. It manages the internal HTTP client, retry logic, and provides access to all task-specific modules. You should initialize this once and maintain it throughout the lifecycle of your application.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.chat().ask("Spark", "Hello!").thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputHello! How can I assist you with your Minecraft server today?

Syntax Standard

In the Official SDK, you first create your connection object and then use that object to send prompts. While you can technically name your variable anything, all our documentation and Minecraft plugin examples use ravonix. (lowercase) to keep it simple and easy to recognize.

The Standard Structure

1 import ravonixapi.Ravonix;
2 import ravonixapi.models.RavonixResponse;
3 
4 Ravonix ravonix = new Ravonix("Rit_your_api_key");
5 
6 ravonix.chat().ask("Spark", "How are you?")
7        .thenAccept(res -> {
8            System.out.println(res.getOutput());
9        });
✓ ravonix.npc().generate(...)
✓ ravonix.quest().build(...)
✓ ravonix.lore().create(...)

Async Architecture

All Ravonix methods are non-blocking and return a `CompletableFuture<RavonixResponse>`. This is a critical design choice for game development, as it prevents the server's main thread from hanging while waiting for an API response.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.chat().ask("Spark", "How are you?").thenAccept(res -> {
    System.out.println(res.getOutput());
});

Fault Tolerance

Our SDK is designed for production environments where network stability is not always guaranteed. Every client includes an automated retry layer that handles temporary outages or rate limits using an exponential backoff algorithm.

2^n Backoff

Wait times increase exponentially with each failure to reduce server load.

Auto-Recovery

Automatic parsing of 429 and 5xx errors ensures a graceful recovery process.

Module

NPC Dialogue

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.npc().generate("Spark", "What are you mining?").thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputJust some iron and coal. The deep dark is getting closer, and I need to fortify the walls before night falls.
Module

General Chat

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.chat().ask("Spark", "How do I build a portal?").thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputTo build a Nether portal, place obsidian in a 4x5 vertical frame and light the bottom with Flint and Steel.
Module

World History

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.lore().create("Void", "The legend of the lost temple").thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputThousands of years ago, the desert was a lush kingdom. When the sun scorched the land, the pharaohs built temples deep underground...
Module

Technical Aid

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.assistant().query("Forge", "Command to give speed").thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response Output/effect give @a[distance=..10] minecraft:speed 30 1
Module

Quest Builder

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.quest().build("Void", "A challenge in a swamp").thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputQuest: The Witch's Brew. Objective: Collect 10 Slimeballs and 1 Cauldron. Reward: 5 Potions of Healing.
Module

Roleplay Hub

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.roleplay().start("Forge", messages).thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputAye, I remember you from the tavern. Still looking for that lost map, I see?
Module

Direct Custom

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.custom().call("Spark", "Respond with: OK").thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputOK
Request Tool

Personality

The `personality` tool allows you to define a persistent persona for the AI. This injects a global identity that influences the tone, vocabulary, and behavior of the character throughout the generation session.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;
import ravonixapi.models.RavonixRequest;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

RavonixRequest request = new RavonixRequest("Spark", "What are you mining?")
    .setPersonality("A talkative pirate looking for treasure");

ravonix.npc().generate(request).thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputAhoy there, matey! I be diggin' for more than just iron—somewhere in these depths lies the lost gold of the Kraken!
Request Tool

Temperature

The `temperature` tool controls the randomness of the output. Lower values (e.g., 0.2) make the AI more focused and deterministic, while higher values (e.g., 1.5) increase creativity and variety.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;
import ravonixapi.models.RavonixRequest;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

RavonixRequest request = new RavonixRequest("Spark", "Describe a block")
    .setTemperature(1.2);

ravonix.chat().ask(request).thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputA block of ancient debris is a rare, fossilized remnant found deep within the Nether, pulsing with a dark, resilient energy from eons past.
Request Tool

Max Tokens

The `max_tokens` tool sets a hard limit on the length of the generated response. This is essential for managing server resources and controlling the verbosity of AI interactions.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;
import ravonixapi.models.RavonixRequest;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

RavonixRequest request = new RavonixRequest("Spark", "Tell me a story")
    .setMaxTokens(50);

ravonix.chat().ask(request).thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputOnce upon a time in a world made of cubes, a lonely creeper found a friend...
Request Tool

Top P

The `top_p` tool (Nucleus Sampling) adjusts diversity by limiting word choice to the top percentage of likely candidates. It provides an alternative to temperature for controlling the sampling distribution.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;
import ravonixapi.models.RavonixRequest;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

RavonixRequest request = new RavonixRequest("Spark", "How are you?")
    .setTopP(0.1);

ravonix.chat().ask(request).thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputI am doing well, thank you. How can I help you today?
Request Tool

Stop Sequences

The `stop` tool allows you to specify sequences where the API will stop generating further tokens. This is useful for preventing the AI from generating repetitive content or ending a response prematurely.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;
import ravonixapi.models.RavonixRequest;
import java.util.List;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

RavonixRequest request = new RavonixRequest("Spark", "List colors:")
    .setStop(List.of("Blue"));

ravonix.chat().ask(request).thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputRed, Green, Yellow,
Request Tool

Choices (N)

The `n` tool controls the number of choices to generate for a single prompt. This is useful for generating multiple creative variations for a given input.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;
import ravonixapi.models.RavonixRequest;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

RavonixRequest request = new RavonixRequest("Spark", "Hello!")
    .setN(2);

ravonix.chat().ask(request).thenAccept(res -> {
    System.out.println(res.getOutput());
});
Response OutputChoice 1: Hello! How can I help? | Choice 2: Greetings! What's on your mind?

Model Tiers

Every Ravonix endpoint can be routed through one of three distinct model tiers. Choosing the correct tier is vital for optimizing performance, intelligence, and project economics.

Spark Node

The high-efficiency tier. Spark is optimized for speed and high-concurrency workloads. It mimics relatable player behavior, making it the perfect choice for server-wide chat bots and simple NPC interactions where latency is critical.

Forge Node

The technical balanced tier. Forge is deeply grounded in technical game mechanics and Minecraft developer documentation. Use this for mentor NPCs, survival advice, and complex technical assistance.

Void Node

The architect reasoning tier. Void is our highest intelligence model, capable of deep narrative planning, multi-stage quest logic, and world-scale historical generation where complexity outweighs speed.

Technical Data

The Error

The `RavonixResponse` object provides access to all metadata returned by the server. When an exception is thrown, the error message contains the specific reason for failure provided by our nodes.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

ravonix.chat().ask("Spark", "Hello!").thenAccept(res -> {
    // 1. Get unique Chat/Request ID
    String chatId = res.getId();
    
    // 2. Get Model used
    String model = res.getModel();
    
    // 3. Get detailed Token Usage
    int inputTokens = res.getUsage().getInputTokens();
    int outputTokens = res.getUsage().getOutputTokens();
    int totalTokens = res.getUsage().getTotalTokens();
    
    // 4. In case of success, get output
    System.out.println("ID: " + chatId);
    System.out.println("Model: " + model);
    System.out.println("Tokens: In(" + inputTokens + ") Out(" + outputTokens + ")");
    System.out.println("Result: " + res.getOutput());
}).exceptionally(e -> {
    // 5. Get Error Message from Server
    System.err.println("Server Error: " + e.getMessage());
    return null;
});
Response OutputID: rx_928374 | Model: Spark | Tokens: In(10) Out(32) | Result: Hello! How can I help?
Fault Tolerance

Exceptions

The SDK identifies and categorizes API errors into specific Java exceptions. When an error occurs, you can extract detailed server-side error messages and reasons from the exception.

import ravonixapi.Ravonix;
import ravonixapi.models.RavonixResponse;
import ravonixapi.exceptions.*;

Ravonix ravonix = new Ravonix("Rit_YOUR_API_KEY");

try {
    RavonixResponse res = ravonix.chat().ask("Spark", "Prompt").join();
} catch (AuthenticationException e) {
    // Rit_ key is invalid or revoked
    System.err.println("Auth Error: " + e.getMessage());
} catch (RateLimitException e) {
    // Project has reached its RPM/TPM tier limit
    System.err.println("Limit Hit: " + e.getMessage());
} catch (ServerException e) {
    // API node is experiencing congestion or outage
    System.err.println("Server Node Error: " + e.getMessage());
} catch (RavonixException e) {
    // Generic SDK error
    System.err.println("General Error: " + e.getMessage());
}
Response OutputLimit Hit: RPM limit reached | Reason: Starter plan allows 20 RPM