Unreal Engine API Reference

UAtelicoAISettings : UDeveloperSettings

Configuration for the Atelico AI Engine. Appears in Project Settings under "Atelico AI". These settings are read at engine initialization and used to configure the native backend. Some settings (like SchedulingMode) can also be changed at runtime via UAtelicoAISubsystem methods.

Properties

Property	Type	Description
ModelDirectory	FString	Custom directory path for model file storage and caching. Leave empty to use the platform default cache directory. When set, models are downloaded to and loaded from this directory instead.

UAtelicoAISubsystem : UGameInstanceSubsystem

Main Atelico AI subsystem. Provides access to all engine capabilities including LLM chat completions, image generation, embeddings, classifiers, guardrails, LoRA adapters, key-value stores, and ANN vector search.

Access via: GetGameInstance()->GetSubsystem<UAtelicoAISubsystem>()

Persists across level transitions. Automatically initialized and shut down with the game instance. Configuration is loaded from UAtelicoAISettings (Project Settings > Atelico AI).

Properties

Property	Type	Description
OnTokenReceived	FOnTokenReceived	Broadcast each frame during streaming chat when a new token is generated. Bind to this delegate to update UI text incrementally as the model generates. Only fires between ChatCompletionStream and OnChatCompleted/OnChatFailed.
OnChatCompleted	FOnChatCompleted	Broadcast when a streaming chat completion finishes successfully. The payload is the full ChatCompletionResponse JSON string. Always preceded by zero or more OnTokenReceived calls.
OnChatFailed	FOnChatFailed	Broadcast when a streaming chat completion fails with an error. The payload is a human-readable error message. After this fires, no further OnTokenReceived calls will occur for the failed stream.
OnImageGenerated	FOnImageGenerated	Broadcast when an asynchronous image generation completes. The payload is the ImageGenerationResponse JSON string containing base64-encoded PNG image data.
OnAudioChunkReceived	FOnAudioChunkReceived	Fired per chunk during a streaming TTS synthesis.
OnAudioCompleted	FOnAudioCompleted	Fired when a streaming TTS synthesis finishes successfully.
OnAudioFailed	FOnAudioFailed	Fired when a streaming TTS synthesis fails. Payload is an error message.

Methods

static bool IsCigD3D12Supported(int32 DeviceIndex = 0)

Query whether the GPU supports Compute-in-Graphics (CiG) with D3D12. CiG allows inference and rendering to share GPU hardware scheduling, reducing context-switch overhead. Requires NVIDIA R570+ driver, CUDA 12.8+, and Ada Lovelace+ GPU.

• DeviceIndex: GPU device index to query (default: 0, the primary GPU).

Returns: true if CiG with D3D12 is supported on the specified device; false otherwise.

static bool IsCigVulkanSupported(int32 DeviceIndex = 0)

Query whether the GPU supports Compute-in-Graphics (CiG) with Vulkan. CiG allows inference and rendering to share GPU hardware scheduling, reducing context-switch overhead. Requires NVIDIA R570+ driver, CUDA 12.9+, and Ada Lovelace+ GPU.

• DeviceIndex: GPU device index to query (default: 0, the primary GPU).

Returns: true if CiG with Vulkan is supported on the specified device; false otherwise.

FString ChatCompletion(const FString& RequestJson) [BlueprintCallable]

Synchronous chat completion (blocks the game thread until generation completes).

• RequestJson: ChatCompletionRequest JSON string (OpenAI format) with fields: model (required) - Model ID in "backend::org/model" format, messages (required) - array of role/content message objects, max_tokens - maximum tokens to generate (default: 256), temperature - sampling temperature 0.0-2.0 (default: 0.7), top_p - nucleus sampling threshold (default: 1.0), response_format - optional JSON schema constraint for structured output, speculative - optional { proposer, k } for multi-token (speculative) decoding to speed up generation (proposer: "prompt_lookup" or "lookahead"); greedy output is unchanged.

Returns: ChatCompletionResponse JSON string with id, choices (array of message and finish_reason), and usage (token counts). Returns empty string on error.

Example input:

{"model":"in-memory::meta-llama/Llama-3.2-1B-Instruct-GGUF","messages":[{"role":"user","content":"Hello"}],"max_tokens":100}

Example output:

{"id":"chatcmpl-abc123","choices":[{"message":{"role":"assistant","content":"Hi! How can I help?"},"finish_reason":"stop"}],"usage":{"prompt_tokens":5,"completion_tokens":8,"total_tokens":13}}

FString RepairJson(const FString& Input, const FString& DefaultJson) [BlueprintCallable]

Repair a possibly-truncated or malformed JSON string.

Stateless — no engine required. The common case is a structured-generation response cut off by a token limit (finish_reason == "length"), e.g. {"a": 1, "b": "hel — valid up to the cut but unparseable as a whole. This completes it best-effort: complete fields are kept, a truncated string value is closed and kept, a dangling key with no value is dropped, and open objects/arrays are closed.

Caveat: a value truncated mid-token is kept as-is. Repair is a safety net — prefer checking finish_reason and raising max_tokens.

• Input: The JSON string to repair.
• DefaultJson: Optional JSON string whose fields fill any missing/null fields in the result (fields present in Input win). Pass an empty string for no default. Returns: The repaired JSON string.

Example input:

{"a": 1, "b": "hel

Example output:

{"a":1,"b":"hel"}

bool ChatCompletionStream(const FString& RequestJson) [BlueprintCallable]

Start a streaming chat completion. Tokens arrive via OnTokenReceived each frame. When complete, OnChatCompleted fires with the full response. On failure, OnChatFailed fires with an error message. The stream field is set automatically.

• RequestJson: ChatCompletionRequest JSON string (same schema as ChatCompletion).

Returns: true if the stream started successfully; false on immediate failure (e.g., model not loaded, malformed JSON).

Example input:

{"model":"in-memory::meta-llama/Llama-3.2-1B-Instruct-GGUF","messages":[{"role":"user","content":"Tell me a story."}],"max_tokens":512}

FString TextCompletion(const FString& RequestJson) [BlueprintCallable]

Synchronous text completion (blocks the game thread). Continues a raw text prompt without chat formatting or role-based message structure.

• RequestJson: CompletionRequest JSON string with fields: model (required) - Model ID in "backend::org/model" format, prompt (required) - text prompt to continue, max_tokens - maximum tokens to generate, temperature - sampling temperature 0.0-2.0.

Returns: CompletionResponse JSON string with id, choices (array of text and finish_reason), and usage (token counts). Returns empty string on error.

Example input:

{"model":"in-memory::meta-llama/Llama-3.2-1B-Instruct-GGUF","prompt":"The dragon descended upon the village and","max_tokens":100}

Example output:

{"id":"cmpl-abc123","choices":[{"text":" breathed fire across the rooftops...","finish_reason":"stop"}],"usage":{"prompt_tokens":8,"completion_tokens":12,"total_tokens":20}}

FString Respond(const FString& RequestJson) [BlueprintCallable]

Synchronous response request following the OpenAI Responses API format. Unlike ChatCompletion, this accepts a flat input string or message array and returns structured output items.

• RequestJson: ResponseRequest JSON string with fields: model (required) - Model ID in "backend::org/model" format, input - user input text or message array, instructions - system instructions, max_output_tokens - maximum tokens to generate, temperature - sampling temperature 0.0-2.0.

Returns: Response JSON string with id, output (array of typed output items), and usage (token counts). Returns empty string on error.

Example input:

{"model":"in-memory::meta-llama/Llama-3.2-1B-Instruct-GGUF","input":"What is the capital of France?","instructions":"Answer concisely.","max_output_tokens":50}

Example output:

{"id":"resp-abc123","output":[{"type":"message","content":"The capital of France is Paris."}],"usage":{"prompt_tokens":12,"completion_tokens":8,"total_tokens":20}}

FString Tokenize(const FString& ModelId, const FString& Text) [BlueprintCallable]

Encode text into token IDs using a loaded model's tokenizer (blocking).

Loads the model on demand if it isn't already resident. Useful for budgeting prompt length against the context window before submitting a request, or for pre-tokenizing prefixes that will be reused.

• ModelId: Model identifier in "backend::org/model" format (e.g. "in-memory::meta-llama/Llama-3.2-3B-Instruct-Q4_K_M").
• Text: UTF-8 text to tokenize.

Returns: JSON string with the token sequence: {"model_id": "in-memory::...", "tokens": [128000, 9906, 11, 1917, 0]} Returns empty string on error.

Example input: ModelId="in-memory::meta-llama/Llama-3.2-3B-Instruct-Q4_K_M", Text="Hello, world!" Example output:

{"model_id":"in-memory::meta-llama/...","tokens":[128000,9906,11,1917,0]}

FString Detokenize(const FString& RequestJson) [BlueprintCallable]

Decode a token ID sequence back into text using a loaded model's tokenizer (blocking).

• RequestJson: JSON detokenize request: { "model_id": "in-memory::meta-llama/Llama-3.2-3B-Instruct-Q4_K_M", "tokens": [128000, 9906, 11, 1917, 0], "skip_special_tokens": true } skip_special_tokens defaults to true when omitted; set to false to keep tokens like <|begin_of_text|> in the output.

Returns: JSON string with the decoded text: {"text": "Hello, world!"} Returns empty string on error.

FString ModelCapabilities(const FString& ModelId) [BlueprintCallable]

Inspect a loaded model's static capabilities (vocab size, context window, dtype, active backend). Loads the model on demand.

• ModelId: Model identifier in "backend::org/model" format.

Returns: JSON ModelCapabilities: { "model_id": "in-memory::meta-llama/Llama-3.2-3B-Instruct-Q4_K_M", "vocab_size": 128256, "max_position_embeddings": 131072, "dtype": "Q4_K_M", "backend_kind": "metal" } Returns empty string on error.

FString GenerateImage(const FString& RequestJson) [BlueprintCallable]

Generate an image from a text prompt (blocking). Returns base64-encoded PNG data.

• RequestJson: ImageGenerationRequest JSON string (OpenAI Images API format) with fields: model (required) - image model ID in "backend::org/model" format, prompt (required) - text description of the desired image, size - image dimensions as "WxH" (default: "512x512"), n - number of images to generate (default: 1), response_format - "b64_json" (default) or "url".

Returns: ImageGenerationResponse JSON string with created (Unix timestamp) and data (array of base64-encoded PNG objects). Returns empty string on error.

Example input:

{"model":"in-memory::PixArt-alpha/PixArt-Sigma-XL-2-1024-MS","prompt":"A medieval castle at sunset","size":"512x512","n":1}

Example output:

{"created":1700000000,"data":[{"b64_json":"iVBORw0KGgoAAAANSUhEUg..."}]}

FString RemoveBackground(const FString& RequestJson) [BlueprintCallable]

Remove the background from an image (blocking). Takes a base64-encoded image and returns a PNG with a transparent background.

• RequestJson: JSON string with fields: image (required) - base64-encoded input image (PNG or JPEG), model - background removal model ID (uses default if omitted).

Returns: JSON string with b64_json field containing the base64-encoded PNG with transparent background. Returns empty string on error.

Example input:

{"image":"iVBORw0KGgoAAAANSUhEUg..."}

Example output:

{"b64_json":"iVBORw0KGgoAAAANSUhEUg..."}

FString SynthesizeAudio(const FString& RequestJson) [BlueprintCallable]

Synthesize speech from text (blocking). Returns base64-encoded WAV audio.

• RequestJson: AudioSpeechRequest JSON string with fields: model (required) — model id, e.g. "in-memory::tts" (default Kokoro 82M), "in-memory::kokoro-82m", or "in-memory::pocket-tts". Bare ids accepted after the prefix: tts / kokoro / kokoro-82m / pocket / pocket-tts. input (required) — text to synthesize. voice — voice id (default "af_heart"). Pocket TTS ships 24 built-in English voices (alba, ian, morgan, kate, …). speed — 0.25–4.0 multiplier (default 1.0).

Returns: JSON string with fields: audio_b64 (base64-encoded WAV bytes), duration_seconds, format, sample_rate. Empty string on error.

Example input:

{"model":"in-memory::tts","input":"Hello from Atelico.","voice":"af_heart"}

Example output:

{"audio_b64":"UklGRn...","duration_seconds":1.42,"format":"wav","sample_rate":24000}

FString TranscribeAudio(const FString& RequestJson) [BlueprintCallable]

Transcribe audio to text (blocking). Accepts a base64-encoded WAV file and returns the transcription.

• RequestJson: Transcription request JSON with fields: model (required) — model id, e.g. "in-memory::whisper" (default resolves to whisper-base.en), "in-memory::whisper-large-v3-turbo", "in-memory::distil-large-v3". audio_b64 (required) — base64-encoded WAV file (RIFF + PCM). The plugin decodes the WAV header to obtain the sample rate. language — ISO 639-1 code ("en", "ja", …) or omit for auto-detect. response_format — "json" (default) or "verbose_json" (adds segments). temperature — decoder sampling temperature (0.0 = greedy). timestamp_granularities — array of "segment" and/or "word".

Returns: AudioTranscriptionResponse JSON string with text, language, duration fields. Empty string on error.

Example input:

{"model":"in-memory::whisper","audio_b64":"UklGRn...","language":"en"}

Example output:

{"text":"Hello from Atelico.","language":"en","duration":1.4}

bool SynthesizeAudioStream(const FString& RequestJson) [BlueprintCallable]

Start a streaming TTS synthesis. Chunks arrive via OnAudioChunkReceived one per sentence/clause; OnAudioCompleted fires after the final chunk. Returns true if the stream was started successfully.

• RequestJson: Same schema as SynthesizeAudio; the stream field is set to true automatically.

FString AudioToFace(const TArray<float>& Pcm, int32 SampleRate, const FString& Character) [BlueprintCallable]

Drive facial animation from speech audio (Audio-to-Face, blocking).

Converts a mono PCM waveform into a timeline of facial blendshape weights (52 ARKit-style coefficients per frame) that can be applied to a character's face mesh for lip-sync and expression. The Audio-to-Face engine is a standalone handle, created lazily on the first call and reused across subsequent calls.

• Pcm: Mono PCM samples as 32-bit floats in the range -1.0 to 1.0.
• SampleRate: Sample rate of the PCM data in Hz (e.g. 16000).
• Character: Character voice/face profile: "claire", "james", or "mark" (case-insensitive). Unrecognized values default to "claire".

Returns: JSON array of frames, each with time_seconds and weights (52 blendshape floats). Returns "[]" on error (e.g. engine creation failed).

Example output:

[{"time_seconds":0.0,"weights":[0.01,0.0,0.12]},{"time_seconds":0.033,"weights":[0.05,0.02,0.18]}]

FString Embed(const FString& RequestJson) [BlueprintCallable]

Generate embedding vectors for one or more input texts (blocking). Embeddings are dense float vectors representing the semantic meaning of text, useful for similarity search, clustering, and classification.

• RequestJson: EmbeddingRequest JSON string (OpenAI Embeddings API format) with fields: model (required) - embedding model ID in "backend::org/model" format, input (required) - single text string or array of texts to embed.

Returns: EmbeddingResponse JSON string with data (array of embedding float arrays and index values), model, and usage. Returns empty string on error.

Example input:

{"model":"in-memory::sentence-transformers/all-MiniLM-L6-v2","input":["The knight draws his sword."]}

Example output:

{"data":[{"embedding":[0.012,-0.034,0.056],"index":0}],"model":"in-memory::sentence-transformers/all-MiniLM-L6-v2","usage":{"prompt_tokens":7,"total_tokens":7}}

FString EmbedImage(const FString& RequestJson) [BlueprintCallable]

Generate an embedding vector for an image (blocking).

Produces a dense float vector in the same shared embedding space as text (e.g. CLIP), enabling cross-modal similarity search — find images that match a text query, or cluster images by visual content.

• RequestJson: EmbeddingRequest JSON string with fields: model (required) - image embedding model ID (e.g. "clip"), image (required) - base64-encoded PNG image data.

Returns: EmbeddingResponse JSON string with data (array of embedding float arrays and index values), model, and usage. Returns empty string on error.

Example input:

{"model":"clip","image":"iVBORw0KGgoAAAANSUhEUg..."}

Example output:

{"data":[{"embedding":[0.021,-0.044,0.066],"index":0}],"model":"clip","usage":{"prompt_tokens":0,"total_tokens":0}}

FString EmbedAudio(const FString& RequestJson) [BlueprintCallable]

Generate an embedding vector for an audio clip (blocking).

Produces a dense float vector representing the acoustic / semantic content of the audio, useful for audio similarity search, clustering, and cross-modal retrieval.

• RequestJson: EmbeddingRequest JSON string with fields: model (required) - audio embedding model ID, audio (required) - base64-encoded audio data (e.g. WAV).

Returns: EmbeddingResponse JSON string with data (array of embedding float arrays and index values), model, and usage. Returns empty string on error.

Example input:

{"model":"clap","audio":"UklGRn..."}

Example output:

{"data":[{"embedding":[0.013,-0.027,0.041],"index":0}],"model":"clap","usage":{"prompt_tokens":0,"total_tokens":0}}

float Similarity(const FString& ModelId, const FString& TextA, const FString& TextB) [BlueprintCallable]

Compute cosine similarity between two texts using the specified embedding model. Both texts are embedded and their cosine distance is computed. Useful for quick semantic comparisons without managing raw embedding vectors.

• ModelId: Embedding model ID in "backend::org/model" format.
• TextA: First text to compare.
• TextB: Second text to compare.

Returns: Cosine similarity score in the range -1.0 to 1.0, where 1.0 means identical semantic meaning and -1.0 means opposite. Returns -2.0 on error (e.g., model not loaded).

FString ClassifierPredict(const FString& RequestJson) [BlueprintCallable]

Predict the class of input text using a loaded classifier model (blocking). Returns the top prediction along with optional top-k ranked alternatives.

• RequestJson: Classification request JSON string with fields: model_id (required) - classifier model ID, text (required) - input text to classify, top_k - number of top predictions to return (default: 1).

Returns: Classification response JSON string with label (top predicted class), probability (confidence score), and top (array of ranked label/probability pairs). Returns empty string on error.

Example input:

{"model_id":"intent-classifier","text":"I want to buy a health potion","top_k":3}

Example output:

{"label":"purchase","probability":0.92,"top":[{"label":"purchase","probability":0.92},{"label":"inquiry","probability":0.05},{"label":"combat","probability":0.03}]}

FString ClassifierPredictImage(const FString& RequestJson) [BlueprintCallable]

Classify an image using a multi-modal classifier (e.g. DINOv2-backed centroid / KNN / SetFit) (blocking).

The classifier referenced by model_id must have been trained with an image embedder. Calling this against a text-only classifier returns an empty string.

• RequestJson: Image classification request JSON string with fields: model_id (required) - image classifier ID, image_path (required) - absolute filesystem path to the image (PNG / JPEG), top_k - number of top predictions to return (default: all classes).

Returns: Classification response JSON string (same schema as ClassifierPredict). Returns empty string on error.

Example input:

{"model_id":"animals","image_path":"/abs/path/cat.jpg","top_k":3}

Example output:

{"label":"cat","probability":0.91,"top":[{"label":"cat","probability":0.91},{"label":"dog","probability":0.07},{"label":"bird","probability":0.02}]}

FString CheckInput(const FString& Text) [BlueprintCallable]

Check input text against configured safety guardrails before sending to a model. Use this to filter player input before passing it to ChatCompletion or similar methods. Guardrails must be enabled in UAtelicoAISettings for this to return meaningful results.

• Text: The user input text to check against safety rules.

Returns: SafetyVerdict JSON string with action ("allow", "block", or "warn"), checker_name (which guardrail triggered), and optional score and reason fields. Returns empty string on error.

Example output:

{"action":"allow","checker_name":"content-safety","score":0.01}

FString CheckOutput(const FString& Text) [BlueprintCallable]

Check model output text against configured safety guardrails before displaying to the player. Use this to filter AI-generated responses before showing them in the game UI. Guardrails must be enabled in UAtelicoAISettings for this to return meaningful results.

• Text: The model output text to check against safety rules.

Returns: SafetyVerdict JSON string with action ("allow", "block", or "warn"), checker_name (which guardrail triggered), and optional score and reason fields. Returns empty string on error.

Example output:

{"action":"allow","checker_name":"content-safety","score":0.02}

FString CheckImagePrompt(const FString& Prompt) [BlueprintCallable]

Check an image generation prompt against safety guardrails before generating. Use this to filter prompts before passing them to GenerateImage. Guardrails must be enabled in UAtelicoAISettings for this to return meaningful results.

• Prompt: The image generation prompt text to check against safety rules.

Returns: SafetyVerdict JSON string with action ("allow", "block", or "warn"), checker_name (which guardrail triggered), and optional score and reason fields. Returns empty string on error.

Example output:

{"action":"allow","checker_name":"image-safety","score":0.01}

bool LoadAdapter(const FString& ModelId, const FString& AdapterPath) [BlueprintCallable]

Load a LoRA adapter onto a base model. The base model must already be loaded via LoadModel. Only one adapter can be active per model at a time; loading a new adapter replaces the previous one.

• ModelId: Base model ID that the adapter will be applied to, in "backend::org/model" format.
• AdapterPath: File path or HuggingFace model ID for the LoRA adapter weights.

Returns: true if the adapter loaded successfully; false on error (e.g., base model not loaded, adapter weights incompatible).

bool UnloadAdapter(const FString& ModelId) [BlueprintCallable]

Unload the active LoRA adapter from a model, reverting to base model behavior. This frees the adapter weights from memory while keeping the base model loaded.

• ModelId: Model ID to remove the adapter from.

Returns: true if an adapter was found and unloaded; false if no adapter was active or the model is not loaded.

bool SetAdapterScale(const FString& ModelId, float Scale) [BlueprintCallable]

Set the runtime scale (alpha) for the active LoRA adapter on a model. A scale of 1.0 applies the adapter at full strength; 0.0 effectively disables it without unloading. Values between 0.0 and 1.0 blend base and adapted behavior.

• ModelId: Model ID with an active LoRA adapter.
• Scale: Adapter strength multiplier, typically in 0.0 to 1.0.

Returns: true on success; false if no adapter is loaded on the model or on error.

bool LoadModel(const FString& ModelId) [BlueprintCallable]

Pre-load a model synchronously (blocks until the model is fully loaded and ready). The model will be downloaded from HuggingFace Hub if not already cached locally. Once loaded, the model remains in memory until explicitly unloaded or the subsystem shuts down.

• ModelId: Model identifier, e.g. "in-memory::meta-llama/Llama-3.2-1B-Instruct-GGUF".

Returns: true if the model loaded successfully; false on error (e.g., invalid model ID, download failure, insufficient VRAM).

bool UnloadModel(const FString& ModelId) [BlueprintCallable]

Unload a model, freeing its GPU and system memory. Any in-flight inference using this model will be cancelled.

• ModelId: Model identifier previously passed to LoadModel.

Returns: true if the model was found and unloaded; false if the model was not loaded.

bool IsModelLoaded(const FString& ModelId)

Check if a model is currently loaded and ready for inference.

• ModelId: Model identifier to check.

Returns: true if the model is loaded and ready; false otherwise.

FString ListModels() [BlueprintCallable]

List all currently loaded models with their types and memory usage.

Returns: JSON array of model descriptors, each containing id (model identifier), type ("llm", "embedding", "image", or "classifier"), and size_bytes (approximate memory usage). Returns "[]" if no models are loaded.

Example output:

[{"id":"in-memory::meta-llama/Llama-3.2-1B-Instruct-GGUF","type":"llm","size_bytes":1234567890}]

bool CreateKvStore(const FString& ConfigJson) [BlueprintCallable]

Create a new LanceDB-backed key-value store for vector search over game data. This store is vector-in, vector-out: embed text yourself with Embed() and pass vectors to KvStoreInsert/KvStoreQuery. The store's embed_dim must match your embedding model (384 for MiniLM/bge-small, 768 for bge-base).

• ConfigJson: Store configuration JSON string with fields: store_id - store identifier (default "default"), db_path - on-disk LanceDB directory, persisted across restarts (default "./data"), table_name - table within the database (default "entries"), embed_dim - embedding vector dimension; must match your model (default 384), has_priority - blend a priority score into ranking (default false), similarity_weight / priority_weight - blend weights (default 0.5/0.5).

Returns: true if the store was created successfully; false on error.

Example input:

{"store_id":"npc-dialogue","db_path":"./data/npc-dialogue","embed_dim":384}

bool KvStoreInsert(const FString& StoreId, const FString& EntriesJson) [BlueprintCallable]

Insert entries into a KV store. You supply each entry's embedding vector (produce it with Embed()); the store does not embed text for you.

• StoreId: Store identifier from CreateKvStore.
• EntriesJson: JSON array of entry objects, each with: id (required) - unique entry identifier, key_text (required) - searchable text (kept for display/reranking), key_embedding (required) - pre-computed vector; length must equal embed_dim, facets - optional string key/value pairs for exact-match filtering, priority - optional ranking priority (0.0-1.0).

Returns: true on success; false on error (e.g., store not found).

Example input:

[{"id":"mem-001","key_text":"The guard saw a thief at midnight.","key_embedding":[0.1,-0.2,0.05],"facets":{"npc_id":"guard-01"},"priority":0.8}]

FString KvStoreQuery(const FString& StoreId, const FString& QueryJson) [BlueprintCallable]

Query a KV store by vector similarity. You supply the query embedding (embed the query text first); entries are ranked by cosine similarity to it.

• StoreId: Store identifier from CreateKvStore.
• QueryJson: Query parameters JSON string with fields: query_embedding (required) - query vector (length = embed_dim), query_text - optional raw text, passed to the reranker / logs, facet_filters - optional exact-match facet filters, vector_search_limit - ANN candidate pool size (default 20), limit - number of results to return (default 5), use_prefilter - apply facet filters before the ANN search (default true).

Returns: JSON array of results sorted by descending similarity, each containing id, key_text, similarity (cosine), priority, and combined_score. Returns empty string on error.

Example input:

{"query_embedding":[0.1,-0.2,0.05],"facet_filters":{"npc_id":"guard-01"},"limit":5}

Example output:

[{"id":"mem-001","key_text":"The guard saw a thief at midnight.","similarity":0.89,"priority":0.8,"combined_score":0.87}]

FString KvStoreScan(const FString& StoreId, const FString& Filter, int32 Limit) [BlueprintCallable]

Scan entries in a KV store with an optional facet filter (no vector search). Returns entries in insertion order, useful for iterating over store contents.

• StoreId: Store identifier from CreateKvStore.
• Filter: SQL-like filter expression, or empty string for no filter.
• Limit: Maximum number of entries to return.

Returns: JSON array of entries in insertion order, each containing id, key_text, and priority. Returns empty string on error.

Example output:

[{"id":"mem-001","key_text":"The guard saw a thief at midnight.","priority":0.8}]

bool DestroyKvStore(const FString& StoreId) [BlueprintCallable]

Destroy a KV store and release all associated resources, including embedded vectors and stored entries. The store ID cannot be reused until a new store is created with it.

• StoreId: Store identifier from CreateKvStore.

Returns: true if the store was found and destroyed; false if no store exists with that ID.

bool KvStoreCreateFtsIndex(const FString& StoreId, const FString& Column) [BlueprintCallable]

Create a full-text-search (FTS) index on a string column of a KV store.

Required before calling KvStoreLexicalQuery or KvStoreHybridQuery. Typical column choices: "key_text" (the search keys) or any string-typed value column. Indexing is a one-time per-store operation.

• StoreId: Store identifier from CreateKvStore.
• Column: Column name to index (must be string-typed in the schema).

Returns: true on success.

FString KvStoreLexicalQuery(const FString& StoreId, const FString& QueryJson) [BlueprintCallable]

Lexical (full-text) retrieval against an FTS-indexed column. Returns rows ranked by BM25 relevance.

The target column must have an FTS index — see KvStoreCreateFtsIndex.

• StoreId: Store identifier from CreateKvStore.
• QueryJson: LexicalSearchQuery JSON string: { "text": "dragon attack", "column": "key_text", "filter": null, "limit": 10 }

Returns: JSON array of KvResult rows. The combined_score field carries the BM25 score. Returns empty string on error.

FString KvStoreHybridQuery(const FString& StoreId, const FString& QueryJson) [BlueprintCallable]

Hybrid (vector + lexical) retrieval with weighted-sum reranking.

Each branch returns up to effective_per_branch_limit candidates; scores are min-max normalised independently and combined as vector_weight * vec_norm + lexical_weight * lex_norm. The FTS column must have an FTS index (see KvStoreCreateFtsIndex).

• StoreId: Store identifier from CreateKvStore.
• QueryJson: HybridSearchQuery JSON string with fields: embeddings (array of float, required) - query embedding vector, text (string, required) - query text for the FTS branch, fts_column (string, required) - FTS-indexed column name, filter (string|null) - optional SQL WHERE filter, limit (int) - final number of merged results, per_branch_limit (int) - per-branch top-k (0 defaults to 2 * limit), vector_weight (float), lexical_weight (float) - merge weights.

Returns: JSON object on success: { "results": [...KvResult...], "scores": [...] }. Each result row's combined_score equals the corresponding merged_score in scores. Returns empty string on error.

int64 CreateAnnIndex(const FString& ConfigJson) [BlueprintCallable]

Create an Approximate Nearest Neighbor (ANN) index backed by HNSW for fast vector similarity search. Use this for custom embedding workflows where you manage raw vectors directly instead of using the higher-level KV store.

• ConfigJson: Index configuration JSON string with fields: dim (required) - vector dimensionality (must match inserted vectors), max_elements (required) - maximum number of vectors the index can hold, m (default: 16) - HNSW connections per node (higher = better recall, more memory), ef_construction (default: 200) - build-time search width, ef_search (default: 50) - query-time search width.

Returns: Index handle ID (positive int64) on success, or 0 on failure.

Example input:

{"dim":384,"max_elements":10000,"m":16,"ef_construction":200}

bool BuildAnnIndex(int64 IndexId) [BlueprintCallable]

Build the ANN index graph. Must be called after all insertions and before any searches. This operation is O(n * log(n)) and may take noticeable time for large indices.

• IndexId: Index handle from CreateAnnIndex.

Returns: true if the graph was built successfully; false on error (e.g., invalid handle, no vectors inserted).

FString SearchAnnIndex(int64 IndexId, const TArray<float>& QueryVector, int32 K) [BlueprintCallable]

Search for the k nearest neighbors in the ANN index. The index must have been built via BuildAnnIndex before searching.

• IndexId: Index handle from CreateAnnIndex.
• QueryVector: Query vector with length matching the index's configured dim.
• K: Number of nearest neighbors to return.

Returns: JSON array of results sorted by ascending distance, each containing label_id (application-defined label from insertion) and distance (lower is closer). Returns "[]" on error or if the index is empty.

Example output:

[{"label_id":42,"distance":0.05},{"label_id":17,"distance":0.12},{"label_id":99,"distance":0.31}]

bool DestroyAnnIndex(int64 IndexId) [BlueprintCallable]

Destroy an ANN index and free all associated memory, including stored vectors and the HNSW graph structure.

• IndexId: Index handle from CreateAnnIndex.

Returns: true if the index was found and destroyed; false if no index exists with that handle.

void SetSchedulingMode(EAtelicoSchedulingMode Mode) [BlueprintCallable]

Set the GPU scheduling mode to control how rendering and inference share GPU time. Takes effect immediately for subsequent inference operations. Can also be configured statically via UAtelicoAISettings::SchedulingMode in Project Settings.

• Mode: The desired scheduling priority balance: PrioritizeCompute (minimize inference latency), Balance (default, share GPU time evenly), or PrioritizeGraphics (maximize rendering FPS).

void SetVramBudgetMb(int32 Mb) [BlueprintCallable]

Set the maximum VRAM budget in megabytes for AI model storage. The engine will refuse to load models that would exceed this limit. Use 0 for unlimited (uses all available VRAM as needed).

• Mb: VRAM budget in megabytes. Use 0 for unlimited.

void SetTargetTps(int32 Tps) [BlueprintCallable]

Set the target tokens-per-second rate for inference pacing. The engine will yield GPU time between tokens to stay near this rate, freeing GPU cycles for rendering. Useful for dialogue systems where tokens should appear at readable speed rather than as fast as possible.

• Tps: Target tokens per second. Use 0 for unlimited (fastest possible).