Godot API Reference

AtelicoEngineNode

The main Godot node for the Atelico AI Engine.

Add as a child node in your scene tree and call initialize_engine to configure backends before using any LLM, embedding, or image generation methods.

Signals emitted by this node:

• inference_token_generated(job_id: int, chunk_json: String) -- a new token chunk arrived during streaming chat/text completion.
• inference_completed(job_id: int, success: bool) -- a streaming LLM request finished (success=true) or failed (success=false).
• image_generation_chunk(job_id: int, response_json: String) -- a progress chunk from streaming image generation.
• image_generation_completed(job_id: int, success: bool) -- streaming image generation finished.
• model_loading_completed(success: bool) -- engine initialization done.
• async_request_completed(job_id: int, response_json: String) -- a non-blocking (async) request completed. response_json is empty on error.

Signals

inference_token_generated

Emitted once per token during a streaming LLM request (llm_chat_stream or llm_respond_stream).

• job_id: matches the return value of the streaming method.
• chunk_json: a ChatCompletionChunk or ResponseStreamDelta JSON string.

inference_completed

Emitted when a streaming LLM request finishes.

• job_id: matches the return value of the streaming method.
• success: true if generation completed normally, false on error.

image_generation_chunk

Emitted for each progress update during streaming image generation (image_generate_stream).

• job_id: matches the return value of image_generate_stream.
• response_json: an ImageGenerationResponse JSON string with partial or complete image data.

image_generation_completed

Emitted when streaming image generation finishes.

• job_id: matches the return value of image_generate_stream.
• success: true if generation completed normally, false on error.

audio_synthesis_chunk

Emitted for each chunk during streaming TTS synthesis (audio_synthesize_stream).

• job_id: matches the return value of audio_synthesize_stream.
• chunk_json: an AudioSpeechChunk JSON string with fields sequence, audio (base64 WAV), duration_seconds, text.

audio_synthesis_completed

Emitted when streaming TTS synthesis finishes.

• job_id: matches the return value of audio_synthesize_stream.
• success: true on normal completion, false on error.

model_loading_completed

Emitted when initialize_engine finishes configuring backends.

• success: true if at least one backend was configured successfully.

async_request_completed

Emitted when a non-blocking (async) request completes. Fired by llm_chat_async and embed_async.

• job_id: matches the return value of the async method.
• response_json: the full JSON response string (empty on error).

model_download_manifest

Fires once per download job, before any model_download_progress events, with the full file list. Each entry is a Dictionary {"path": String, "size": int}. Skipped when the engine can't probe the store (offline / HF-only models).

model_download_progress

Per-event signal for an async download (model_download_async, adapter_download_async). job_id matches the return value of the async method; kind is "model" or "adapter".

file_* params describe the file currently in progress (reset on each new file); job_* params describe the whole job (cumulative, never reset). Drive a unified bar off job_bytes_done / job_total_bytes; use the file_* params for a detail label.

Any _total_bytes param is -1 when the store didn't advertise a size, and file_count is 0 until the engine's preflight LIST has been observed.

model_download_completed

Emitted when an async model or adapter download finishes.

• job_id: matches the return value of the async method.
• success: true if all files downloaded successfully.
• error: error message on failure, empty string on success.

Methods

set_env_var(key: GString, value: GString)

Set a process environment variable.

Useful for configuring RUST_LOG, HF_TOKEN, or OPENAI_API_KEY from GDScript before initializing the engine.

Inputs

• key -- environment variable name (e.g. "RUST_LOG", "HF_TOKEN").
• value -- value to set.

Outputs

No return value.

Example

Input: key="RUST_LOG", value="debug"
Output: (none -- environment variable is set for the process)

initialize_engine(backends_config: Array<VarDictionary>)

Configure the engine router with an array of backend definitions.

GPU scheduling configuration is read from the AtelicoSingleton at init time. Call AtelicoSingleton.set_gpu_scheduling_mode() etc. before calling this method to configure GPU sharing behavior.

Inputs

• backends_config -- Array of Dictionaries, each with:
  • "name" (string, required) -- logical name for the backend (e.g. "in-memory").
  • "type" (string, required) -- "in-memory" (local inference) or "proxy" (remote API).
  • "config" (Dictionary, required) -- backend-specific settings:
    • For "proxy": {"base_url": "...", "api_key": "..."}.
    • For "in-memory": empty dictionary {} is valid.

Outputs

No return value. Emits model_loading_completed(true) signal on success.

Example

Input: [{"name":"in-memory","type":"in-memory","config":{}}]
Output: (signal) model_loading_completed(true)

llm_chat(request_str: GString) -> GString

Synchronous (blocking) chat completion.

Inputs

• request_str -- JSON ChatCompletionRequest:
  • model (string, required) -- model ID in "backend::org/model" format.
  • messages (array, required) -- conversation messages:
    • role (string) -- "system", "user", or "assistant".
    • content (string) -- message text.
  • max_tokens (int) -- maximum tokens to generate.
  • temperature (float) -- controls randomness; lower is more focused and repeatable, higher more varied. 0 = greedy.
  • top_k (int) -- only consider the K most-likely next tokens.
  • top_p (float) -- nucleus sampling: only consider the smallest set of tokens whose probabilities sum to p.
  • min_p (float) -- ignore tokens less likely than this fraction of the most-likely token.
  • repetition_penalty (float) -- discourage repeating words/phrases.
  • seed (int) -- set for reproducible output (same seed + params + prompt -> same result). All sampling parameters are optional: each model has recommended defaults, applied automatically when a request omits them.
  • response_format (object) -- structured output schema.
  • speculative (object) -- optional { proposer, k } for multi-token (speculative) decoding to speed up generation. Off by default. proposer is "prompt_lookup" (recommended for grounded prompts — RAG / summary / code edit; 1.5–2.5× AR speedup) or "lookahead" (general repetitive output; ~1.3× AR). Greedy output is bit-identical to plain AR. See docs/docs/guide/speculative-decoding.mdx for which proposer to use on which workload.

Outputs

JSON ChatCompletionResponse (empty string on error):

• id (string) -- unique response ID.
• choices (array) -- generated completions:
  • message (object) -- { role, content }.
  • finish_reason (string) -- "stop" or "length".
• usage (object) -- { prompt_tokens, completion_tokens, total_tokens }.

Example

Input: {"model":"in-memory::meta-llama/Llama-3.2-1B-Instruct","messages":[{"role":"user","content":"Hello"}],"max_tokens":100}
Output: {"id":"chatcmpl-xxx","choices":[{"message":{"role":"assistant","content":"Hi!"},"finish_reason":"stop"}],"usage":{"prompt_tokens":5,"completion_tokens":3,"total_tokens":8}}

llm_chat_async(request_str: GString) -> i64

Non-blocking chat completion. Runs on a background thread.

Inputs

• request_str -- same JSON ChatCompletionRequest schema as llm_chat.

Outputs

int: a job_id. When inference finishes, the async_request_completed(job_id, response_json) signal is emitted with the full ChatCompletionResponse JSON (or empty string on error).

Example

Input: {"model":"in-memory::llama","messages":[{"role":"user","content":"Hi"}]}
Output: 0 (job_id; then signal async_request_completed(0, "{...}") is emitted)

llm_chat_stream(request_str: GString) -> i64

Streaming chat completion. Tokens arrive via signals.

Inputs

• request_str -- same JSON ChatCompletionRequest schema as llm_chat. The stream field is set automatically.

Outputs

int: a job_id. For each generated token, the inference_token_generated(job_id, chunk_json) signal is emitted where chunk_json is a ChatCompletionChunk:

• id (string) -- chunk ID.
• choices (array) -- [{"delta": {"content": "token"}, "finish_reason": null}]

When generation finishes, inference_completed(job_id, success) is emitted.

Example

Input: {"model":"in-memory::llama","messages":[{"role":"user","content":"Hi"}]}
Output: 0 (job_id; then signals: inference_token_generated(0, "{...}") per token, inference_completed(0, true))

llm_text_complete(request_str: GString) -> GString

Synchronous (blocking) text completion. Continues a raw prompt without chat template formatting.

Inputs

• request_str -- JSON TextCompletionRequest:
  • model (string, required) -- backend-prefixed model ID.
  • prompt (string, required) -- raw text prompt (no chat template).
  • max_tokens (int) -- maximum tokens to generate.
  • temperature, top_k, top_p, min_p, repetition_penalty, seed -- optional sampling parameters (same meanings as async_chat_completions). Each model supplies recommended defaults for any you omit.

Outputs

JSON TextCompletionResponse (empty string on error):

• id (string) -- unique completion ID.
• choices (array) -- [{"text": "...", "index": 0, "finish_reason": "stop"}]
• usage (object) -- { prompt_tokens, completion_tokens, total_tokens }

Example

Input: {"model":"in-memory::llama","prompt":"Once upon a time","max_tokens":50}
Output: {"id":"cmpl-xxx","choices":[{"text":" there was a...","index":0,"finish_reason":"stop"}],"usage":{"prompt_tokens":4,"completion_tokens":50,"total_tokens":54}}

llm_respond(request_str: GString) -> GString

Synchronous (blocking) Responses API call. A higher-level conversational interface that manages conversation state internally.

Inputs

• request_str -- JSON ResponseRequest:
  • model (string, required) -- backend-prefixed model ID.
  • input (string or array) -- user input text or message list.
  • instructions (string) -- system prompt / instructions.
  • max_output_tokens (int) -- maximum tokens to generate.
  • temperature, top_k, top_p, min_p, repetition_penalty, seed -- optional sampling parameters. Each model supplies recommended defaults for any you omit.

Outputs

JSON ResponseResponse (empty string on error):

• id (string) -- unique response ID.
• output (array) -- [{"type": "message", "content": [...]}]
• usage (object) -- { input_tokens, output_tokens }

Example

Input: {"model":"in-memory::llama","input":"What is 2+2?"}
Output: {"id":"resp-xxx","output":[{"type":"message","content":[{"type":"output_text","text":"4"}]}],"usage":{"input_tokens":5,"output_tokens":1}}

llm_respond_stream(request_str: GString) -> i64

Streaming Responses API request. Tokens arrive via signals.

Inputs

• request_str -- same JSON ResponseRequest schema as llm_respond. The stream field is set automatically.

Outputs

int: a job_id. Tokens arrive via inference_token_generated(job_id, chunk_json), and completion is signaled by inference_completed(job_id, success).

Example

Input: {"model":"in-memory::llama","input":"Hello"}
Output: 0 (job_id; then signals: inference_token_generated(0, "{...}") per token, inference_completed(0, true))

llm_tokenize(model_id: GString, text: GString) -> GString

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

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-tokenising prefixes that will be reused.

Inputs

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

Outputs

JSON TokenizeResponse (empty string on error):

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

Example

Input: model_id="in-memory::meta-llama/Llama-3.2-3B-Instruct-Q4_K_M", text="Hello, world!"
Output: {"model_id":"in-memory::meta-llama/Llama-3.2-3B-Instruct-Q4_K_M","tokens":[128000,9906,11,1917,0]}

llm_detokenize(request_str: GString) -> GString

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

Inputs

• request_str -- JSON detokenise 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.

Outputs

JSON DetokenizeResponse (empty string on error):

{"text": "Hello, world!"}

llm_model_capabilities(model_id: GString) -> GString

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

Inputs

• model_id -- model identifier in "backend::model" format.

Outputs

JSON ModelCapabilities (empty string on error):

{
  "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",
  "device": "Cuda(0)",
  "backend_kind": "metal",
  "thinking_style": "native",
  "native_tool_format": "gemma4",
  "recommended_sampling": { "temperature": 1.0, "top_p": 0.95 }
}

device defaults to an empty string on older engines. thinking_style is one of "unsupported"/"thinktags"/"native". native_tool_format and the individual recommended_sampling knobs are omitted when absent. See [Self::llm_model_capabilities_dict] for a typed Godot Dictionary.

llm_model_capabilities_dict(model_id: GString) -> VarDictionary

Inspect a loaded model's static capabilities as a typed Godot Dictionary (no JSON parsing on the GDScript side).

Same backend call as [Self::llm_model_capabilities]; returns an EMPTY dictionary on error. Keys:

• model_id (String), vocab_size (int), max_position_embeddings (int), dtype (String), device (String), backend_kind (String) — always present.
• thinking_style (String) — "unsupported"/"thinktags"/"native".
• native_tool_format (String) — the format tag (e.g. "gemma4"), or an empty string when the model has no native tool block.
• recommended_sampling (Dictionary) — nested; holds temperature, top_p, and/or repetition_penalty (float), and/or top_k (int) only for the knobs the model declares. Empty when the model recommends nothing.

image_generate(request_str: GString) -> GString

Synchronous (blocking) image generation from a text prompt.

Inputs

• request_str -- JSON ImageGenerationRequest:
  • model (string, required) -- backend-prefixed model ID.
  • prompt (string, required) -- text description of the image.
  • n (int) -- number of images to generate (default 1).
  • size (string) -- image dimensions (e.g. "512x512").
  • response_format (string) -- "b64_json" or "url".

Outputs

JSON ImageGenerationResponse (empty string on error):

• created (int) -- Unix timestamp of generation.
• data (array) -- [{"b64_json": "...", "revised_prompt": "..."}]

Example

Input: {"model":"in-memory::PixArt-alpha/PixArt-Sigma-XL-2-512-MS","prompt":"A sunset","size":"512x512"}
Output: {"created":1234567890,"data":[{"b64_json":"iVBORw0KGgo...","revised_prompt":"A sunset"}]}

video_generate(request_str: GString) -> GString

Generate a video (blocking, JSON in / JSON out).

Mirrors image_generate. The OpenAI-shaped VideoGenerationRequest JSON (model, prompt, optional width/height/num_frames/fps/seed/ response_format) is forwarded through the engine router; the returned JSON is a VideoGenerationResponse. Returns an empty GString on any transport-level failure (router not ready, JSON parse error, model error).

audio_synthesize(request_str: GString) -> GString

Synthesize speech from text (blocking).

Inputs

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

Outputs

JSON object (empty string on error):

• audio_b64 (string) -- base64-encoded WAV bytes (RIFF + PCM).
• duration_seconds (float)
• format (string) -- "wav"
• sample_rate (int) -- typically 24000.

Example

Input: {"model":"in-memory::tts","input":"Hello!","voice":"af_heart"}
Output: {"audio_b64":"UklGRn...","duration_seconds":1.42,"format":"wav","sample_rate":24000}

audio_transcribe(request_str: GString) -> GString

Transcribe audio to text (blocking).

Inputs

• request_str -- JSON object:
  • model (string, required) -- e.g. "in-memory::whisper" (default → whisper-base.en), "in-memory::whisper-large-v3-turbo", "in-memory::distil-large-v3".
  • audio_b64 (string, required) -- base64-encoded WAV file (RIFF + PCM). Sample rate is read from the WAV header.
  • language (string) -- ISO 639-1 code ("en", "ja", ...) or omit for auto-detect.
  • response_format (string) -- "json" (default) or "verbose_json" (adds segments).
  • temperature (float) -- decoder sampling temperature (0.0 = greedy).
  • timestamp_granularities (array) -- ["segment"] and/or ["word"].

Outputs

JSON AudioTranscriptionResponse (empty string on error):

• text (string)
• language (string, optional)
• duration (float, optional)
• segments, words (optional, depending on response_format and granularities).

Example

Input: {"model":"in-memory::whisper","audio_b64":"UklGRn..."}
Output: {"text":"Hello from Atelico.","language":"en","duration":1.4}

audio_synthesize_stream(request_str: GString) -> i64

Streaming TTS synthesis. Chunks arrive via signals.

Inputs

• request_str -- JSON AudioSpeechRequest (same schema as audio_synthesize). The stream field is set automatically.

Outputs

int: a job_id. Per-chunk signals fire as audio_synthesis_chunk(job_id, chunk_json), and completion is signaled by audio_synthesis_completed(job_id, success).

Example

Input: {"model":"in-memory::pocket-tts","input":"First. Second.","voice":"alba"}
Output: 7 (job_id; then signals: audio_synthesis_chunk(7, "{...}"), audio_synthesis_completed(7, true))

image_generate_stream(request_str: GString) -> i64

Streaming image generation. Progress chunks arrive via signals.

Inputs

• request_str -- same JSON ImageGenerationRequest schema as image_generate. The stream field is set automatically.

Outputs

int: a job_id. Progress chunks arrive via image_generation_chunk(job_id, response_json), and completion is signaled by image_generation_completed(job_id, success).

Example

Input: {"model":"in-memory::PixArt","prompt":"A cat"}
Output: 0 (job_id; then signals: image_generation_chunk(0, "{...}"), image_generation_completed(0, true))

image_remove_background(request_str: GString) -> GString

Synchronous (blocking) background removal from an image.

Inputs

• request_str -- JSON BackgroundRemovalRequest:
  • model (string, required) -- backend-prefixed model ID.
  • image (string, required) -- base64-encoded image data or URL.

Outputs

JSON response (empty string on error):

• data (array) -- [{"b64_json": "..."}] -- image with background removed.

Example

Input: {"model":"in-memory::briaai/RMBG-1.4","image":"iVBORw0KGgo..."}
Output: {"data":[{"b64_json":"iVBORw0KGgo..."}]}

embed(request_str: GString) -> GString

Synchronous (blocking) text embedding.

Inputs

• request_str -- JSON EmbeddingRequest:
  • model (string, required) -- backend-prefixed embedding model ID.
  • input (string or array of strings) -- text(s) to embed.

Outputs

JSON EmbeddingResponse (empty string on error):

• object (string) -- always "list".
• model (string) -- model used.
• data (array) -- [{"object": "embedding", "index": 0, "embedding": [0.1, ...]}]
• usage (object) -- { prompt_tokens, total_tokens }

Example

Input: {"model":"in-memory::sentence-transformers/all-MiniLM-L6-v2","input":"Hello world"}
Output: {"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2,...]}],"usage":{"prompt_tokens":2,"total_tokens":2}}

embed_async(request_str: GString) -> i64

Non-blocking embedding. Runs on a background thread.

Inputs

• request_str -- same JSON EmbeddingRequest schema as embed.

Outputs

int: a job_id. When embedding finishes, the async_request_completed(job_id, response_json) signal is emitted with the full EmbeddingResponse JSON (or empty string on error).

Example

Input: {"model":"in-memory::all-MiniLM-L6-v2","input":"Hello"}
Output: 0 (job_id; then signal async_request_completed(0, "{...}") is emitted)

embed_image(request_str: GString) -> GString

Synchronous (blocking) image embedding. Embeds a single image into a fixed-dimensional vector via a vision embedder (DINOv2).

Inputs

• request_str -- JSON ImageEmbeddingRequest:
  • model (string, required) -- backend-prefixed vision embedding model ID (e.g. "in-memory::dinov2-small").
  • image (string, required) -- base64-encoded PNG/JPEG image bytes.

Outputs

JSON EmbeddingResponse (same shape as embed; empty string on error):

• object (string) -- always "list".
• model (string) -- model used.
• data (array) -- [{"object": "embedding", "index": 0, "embedding": [0.1, ...]}]
• usage (object) -- { prompt_tokens, total_tokens }

Example

Input: {"model":"in-memory::dinov2-small","image":"iVBORw0KGgo..."}
Output: {"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2,...]}],"usage":{"prompt_tokens":0,"total_tokens":0}}

embed_image_async(request_str: GString) -> i64

Non-blocking image embedding. Runs on a background thread.

Inputs

• request_str -- same JSON ImageEmbeddingRequest schema as embed_image.

Outputs

int: a job_id. When embedding finishes, the async_request_completed(job_id, response_json) signal is emitted with the full EmbeddingResponse JSON (or empty string on error).

Example

Input: {"model":"in-memory::dinov2-small","image":"iVBORw0KGgo..."}
Output: 0 (job_id; then signal async_request_completed(0, "{...}") is emitted)

embed_audio(request_str: GString) -> GString

Synchronous (blocking) audio embedding. Embeds a single audio clip into a fixed-dimensional vector via an audio embedder (CLAP). The resulting vector lives in CLAP's shared text/audio space, so it is directly comparable to a text query embedded by the same model.

Inputs

• request_str -- JSON AudioEmbeddingRequest:
  • model (string, required) -- backend-prefixed audio embedding model ID (e.g. "in-memory::clap-htsat-unfused").
  • audio (string, required) -- base64-encoded RIFF/WAVE bytes (16-bit PCM or 32-bit float, mono/stereo). Downmixed and resampled internally.

Outputs

JSON EmbeddingResponse (same shape as embed; empty string on error):

• object (string) -- always "list".
• model (string) -- model used.
• data (array) -- [{"object": "embedding", "index": 0, "embedding": [0.1, ...]}]
• usage (object) -- { prompt_tokens, total_tokens }

Example

Input: {"model":"in-memory::clap-htsat-unfused","audio":"UklGRn..."}
Output: {"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2,...]}],"usage":{"prompt_tokens":0,"total_tokens":0}}

embed_audio_async(request_str: GString) -> i64

Non-blocking audio embedding. Runs on a background thread.

Inputs

• request_str -- same JSON AudioEmbeddingRequest schema as embed_audio.

Outputs

int: a job_id. When embedding finishes, the async_request_completed(job_id, response_json) signal is emitted with the full EmbeddingResponse JSON (or empty string on error).

Example

Input: {"model":"in-memory::clap-htsat-unfused","audio":"UklGRn..."}
Output: 0 (job_id; then signal async_request_completed(0, "{...}") is emitted)

model_load(model_id: GString) -> bool

Pre-load a model (blocking). Call during loading screens to avoid latency on the first inference request.

Inputs

• model_id -- model ID in "backend::org/model" format (e.g. "in-memory::meta-llama/Llama-3.2-1B-Instruct").

Outputs

bool: true on success, false if the backend is not found or loading fails.

Example

Input: "in-memory::meta-llama/Llama-3.2-1B-Instruct"
Output: true

model_download(model_id: GString, auth_token: GString) -> VarDictionary

Download a model's weights into the local Atelico cache (blocking).

Resolves the model id, downloads safetensors or GGUF files (whichever the resolution path picks), and stops there. Weights are NOT loaded onto the GPU and the model is NOT added to the in-memory cache — the first inference request that names this model will pay the GPU load cost but skip the network download.

Use this when you want to pull weights ahead of time without paying the VRAM cost upfront. If you want the model warm and ready for instant inference instead, use model_load.

Inputs

• model_id -- model ID in "backend::org/model" format (e.g. "in-memory::meta-llama/Llama-3.2-1B-Instruct"). Same format as model_load.
• auth_token -- OPTIONAL per-request bearer token (a rotating Supabase JWT) attached to the http(s) asset-store GETs as Authorization: Bearer <token>. Pass "" for no auth header (unchanged behavior). Never read from the process environment.

Outputs

VarDictionary { "ok": bool, "error": String }. ok is true on success; error carries the underlying failure message on ok = false (empty string on success). Matches the shape async callers see via model_download_completed(job_id, success, error).

Example

Input: "in-memory::prism-ml/Bonsai-1.7B-mlx-1bit"
Output: {"ok": true, "error": ""}

is_model_cached(model_id: GString) -> bool

Returns true if the model's weights are already in the local Atelico cache (in either safetensors or GGUF form).

Pure filesystem check — does not touch the network and does not block on the model thread. Use this to decide whether to show a "this will download X MB" confirmation before calling model_download.

Inputs

• model_id -- model ID in "backend::org/model" format. Same format as model_load / model_download.

Outputs

bool: true if cached, false if missing or the backend is not found.

is_adapter_cached(adapter_id: GString) -> bool

Returns true if the adapter's files are already in the local Atelico cache.

Pure filesystem check; same caveats as is_model_cached.

Inputs

• adapter_id -- bare adapter id (no backend prefix), e.g. "deckgen_latest_bonsai".

Outputs

bool: true if cached, false if missing or no backend is configured.

adapter_download(adapter_id: GString, auth_token: GString) -> VarDictionary

Download an adapter (LoRA) into the local Atelico cache (blocking).

Downloads adapter_config.json and adapter_model.safetensors for the given adapter id from the configured object store. The adapter is NOT bound to any base model and is NOT loaded onto the GPU — that still happens lazily on the first inference request that names it.

Use this during a loading screen to avoid the network cost on the first inference that names this adapter.

Inputs

• adapter_id -- bare adapter id (no backend prefix), e.g. "deckgen_latest_bonsai". Adapter operations don't take a backend:: prefix; if multiple in-memory backends are configured, pick_adapter_backend picks the lexicographically smallest one.

Outputs

VarDictionary { "ok": bool, "error": String }. Same shape as model_download — see there for details.

Example

Input: "deckgen_latest_bonsai"
Output: {"ok": true, "error": ""}

total_size(namespace: GString, id: GString) -> i64

Sum the size of every remote object under <namespace>/<id>/ in the configured object store. Returns -1 when the store is unreachable or the asset is absent.

Blocking — issues a synchronous LIST against the bucket.

Inputs

• namespace -- "models" or "adapters".
• id -- the asset id (without any "backend::" prefix).

model_download_async(model_id: GString, auth_token: GString) -> i64

Download a model's weights into the local Atelico cache asynchronously, streaming progress to the Godot main loop via signals.

Returns a job_id immediately. While the download runs in the background, the engine fires model_download_manifest once with the file list, then model_download_progress per file event (with kind = "model"), and finally model_download_completed when done.

Inputs

• model_id -- model ID in "backend::org/model" format, same as model_download.
• auth_token -- OPTIONAL per-request bearer token (a rotating Supabase JWT) attached to the http(s) asset-store GETs as Authorization: Bearer <token>. Pass "" for no auth header (unchanged behavior). Never read from the process environment.

Outputs

int: the job_id used by the progress / completion signals, or -1 if the backend is not configured.

adapter_download_async(adapter_id: GString, auth_token: GString) -> i64

Download an adapter (LoRA) asynchronously, streaming progress events via signals. Symmetric with [model_download_async].

model_download_progress fires with kind = "adapter" for events emitted by this call.

auth_token is an OPTIONAL per-request bearer token (a rotating Supabase JWT) attached to the http(s) asset-store GETs as Authorization: Bearer <token>. Pass "" for no auth header (unchanged behavior). Never read from the process environment.

lora_load(model_id: GString, adapter_path: GString) -> bool

Load a LoRA adapter onto a model (registers intent; actual loading happens via the model name convention backend::model::adapter).

Inputs

• model_id -- the base model ID to attach the adapter to.
• adapter_path -- filesystem path to a directory containing adapter_config.json and adapter weight files.

Outputs

bool: true on success.

Example

Input: model_id="in-memory::llama", adapter_path="/adapters/my-lora"
Output: true

lora_unload(model_id: GString) -> bool

Unload a LoRA adapter from a model, reverting to base weights.

Inputs

• model_id -- the model whose adapter should be removed.

Outputs

bool: true on success.

Example

Input: "in-memory::llama"
Output: true

lora_set_scale(model_id: GString, scale: f64) -> bool

Set the LoRA runtime scale factor for a model's loaded adapter.

A scale of 1.0 applies the full adapter effect; 0.0 effectively disables it without unloading.

Inputs

• model_id -- the model with a loaded LoRA adapter.
• scale -- scale factor (typically 0.0 to 1.0; 1.0 = full adapter effect).

Outputs

bool: true on success.

Example

Input: model_id="in-memory::llama", scale=0.5
Output: true

Deprecated Methods

chat_completions(request_str: GString) -> GString

DEPRECATED: Use llm_chat instead.

Synchronous chat completion (old API name). Delegates to llm_chat.

Inputs

• request_str -- same as llm_chat.

Outputs

Same as llm_chat.

Example

Input: {"model":"in-memory::llama","messages":[{"role":"user","content":"Hi"}]}
Output: (same as llm_chat -- use llm_chat instead)

async_chat_completions(request_str: GString) -> i64

DEPRECATED: Use llm_chat_async instead.

Non-blocking chat completion (old API name). Delegates to llm_chat_async.

Inputs

• request_str -- same as llm_chat_async.

Outputs

Same as llm_chat_async.

Example

Input: {"model":"in-memory::llama","messages":[{"role":"user","content":"Hi"}]}
Output: (same as llm_chat_async -- use llm_chat_async instead)

stream_chat_completions(request_str: GString) -> i64

DEPRECATED: Use llm_chat_stream instead.

Streaming chat completion (old API name). Delegates to llm_chat_stream.

Inputs

• request_str -- same as llm_chat_stream.

Outputs

Same as llm_chat_stream.

Example

Input: {"model":"in-memory::llama","messages":[{"role":"user","content":"Hi"}]}
Output: (same as llm_chat_stream -- use llm_chat_stream instead)

responses(request_str: GString) -> GString

DEPRECATED: Use llm_respond instead.

Synchronous Responses API call (old API name). Delegates to llm_respond.

Inputs

• request_str -- same as llm_respond.

Outputs

Same as llm_respond.

Example

Input: {"model":"in-memory::llama","input":"Hello"}
Output: (same as llm_respond -- use llm_respond instead)

stream_responses(request_str: GString) -> i64

DEPRECATED: Use llm_respond_stream instead.

Streaming Responses API (old API name). Delegates to llm_respond_stream.

Inputs

• request_str -- same as llm_respond_stream.

Outputs

Same as llm_respond_stream.

Example

Input: {"model":"in-memory::llama","input":"Hello"}
Output: (same as llm_respond_stream -- use llm_respond_stream instead)

embeddings(request_str: GString) -> GString

DEPRECATED: Use embed instead.

Synchronous embedding (old API name). Delegates to embed.

Inputs

• request_str -- same as embed.

Outputs

Same as embed.

Example

Input: {"model":"in-memory::all-MiniLM-L6-v2","input":"Hello"}
Output: (same as embed -- use embed instead)

async_embeddings(request_str: GString) -> i64

DEPRECATED: Use embed_async instead.

Non-blocking embedding (old API name). Delegates to embed_async.

Inputs

• request_str -- same as embed_async.

Outputs

Same as embed_async.

Example

Input: {"model":"in-memory::all-MiniLM-L6-v2","input":"Hello"}
Output: (same as embed_async -- use embed_async instead)

stream_image_generation(request_str: GString) -> i64

DEPRECATED: Use image_generate_stream instead.

Streaming image generation (old API name). Delegates to image_generate_stream.

Inputs

• request_str -- same as image_generate_stream.

Outputs

Same as image_generate_stream.

Example

Input: {"model":"in-memory::PixArt","prompt":"A cat"}
Output: (same as image_generate_stream -- use image_generate_stream instead)

AtelicoSingleton

Engine-level singleton for GPU scheduling and inference configuration.

Registered as AtelicoSingleton and accessible from GDScript via Engine.get_singleton("AtelicoSingleton"). Configure GPU scheduling mode, VRAM budgets, token rate limiting, and frame budgets before calling AtelicoEngineNode.initialize_engine().

Settings configured here are read once at engine initialization time. Changing them after initialize_engine() has no effect.

Methods

set_gpu_scheduling_mode(mode: i32)

Set the GPU scheduling mode to control how GPU time is shared between inference and rendering.

• mode: one of PRIORITIZE_COMPUTE (0), BALANCE (1), or PRIORITIZE_GRAPHICS (2). Invalid values default to BALANCE.

get_gpu_scheduling_mode() -> i32

Get the current GPU scheduling mode as an integer constant.

Returns: one of PRIORITIZE_COMPUTE (0), BALANCE (1), or PRIORITIZE_GRAPHICS (2).

repair_json(input: GString, default_json: GString) -> GString

Repair a possibly-truncated or malformed JSON string.

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. Completes it best-effort: keeps complete fields, closes and keeps a truncated string value, drops a dangling key with no value, and closes open objects/arrays.

• input: the JSON string to repair.
• default_json: 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.

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

set_vram_budget_mb(budget_mb: i32)

Set the maximum VRAM (in megabytes) that inference may use. When exceeded, model loading will be rejected.

• budget_mb: VRAM cap in MB. Set to 0 for unlimited (default). Negative values are clamped to 0.

get_vram_budget_mb() -> i32

Get the configured VRAM budget in MB.

Returns: VRAM budget in megabytes, or 0 if unlimited.

set_target_tokens_per_second(tps: i32)

Set the maximum tokens per second for inference. The inference loop sleeps between tokens to stay under this rate, freeing GPU time for rendering.

• tps: target tokens per second. Set to 0 for unlimited (default). Negative values are clamped to 0.

get_target_tokens_per_second() -> i32

Get the configured token rate limit.

Returns: target tokens per second, or 0 if unlimited.

set_frame_time_ms(ms: i32)

Set the target frame time in milliseconds, used as a hint for adaptive inference throttling. For example, pass 16 for a 60 FPS target or 33 for 30 FPS.

• ms: frame budget in milliseconds. Set to 0 for no frame budget (default). Negative values are clamped to 0.

get_frame_time_ms() -> i32

Get the configured frame time budget in milliseconds.

Returns: frame time in milliseconds, or 0 if no budget is set.

set_lora_pre_merge(enabled: bool)

Configure whether LoRA adapters are pre-merged into base weights at load time.

Pre-merging (the default) bakes the LoRA delta into the base weight, giving zero per-token overhead during inference. This temporarily uses ~2× the base weight's memory during the merge and clones the base weight to support adapter unload.

Disable on memory-constrained devices (iPhone, low-RAM iPads) — A/B matrices are kept and the delta is applied at runtime in forward(). Lower peak memory, small per-token cost.

• enabled: true to pre-merge (default), false for runtime delta.

Must be called BEFORE AtelicoEngineNode.initialize_engine(). Settings change after init has no effect on already-loaded adapters.

get_lora_pre_merge() -> bool

Get the configured LoRA pre-merge policy. Returns the engine default (true) if set_lora_pre_merge has not been called.

is_cig_d3d12_supported() -> bool

Check whether the GPU supports CiG (Compute-in-Graphics) with D3D12. Requires an NVIDIA Ada Lovelace+ GPU with HAGS enabled and R570+ driver.

Returns: true if D3D12 CiG is supported, false otherwise. Always returns false on non-CUDA builds (macOS, CPU-only).

is_cig_vulkan_supported() -> bool

Check whether the GPU supports CiG (Compute-in-Graphics) with Vulkan. Requires an NVIDIA Ada Lovelace+ GPU with CUDA 12.9+ driver.

Returns: true if Vulkan CiG is supported, false otherwise. Always returns false on non-CUDA builds (macOS, CPU-only).

get_gpu_scheduling_mode_raw() -> i32

set_gpu_scheduling_mode_raw(value: i32)

AtelicoClassifierNode

Godot node for embedding-based text classification.

Loads pre-trained classifier models (centroid or KNN/HNSW) and predicts the class of input text, images, or audio. Useful for intent detection, sentiment analysis, or content routing in games.

Usage: Add as a child node, call initialize(), then load_classifier() with a classifier ID and directory path, then predict_text() / predict_image() / predict_audio() to classify by modality.

Methods

initialize() -> bool

Initialize the classifier engine. Must be called before load_classifier or any predict_* call.

Inputs

(none)

Outputs

bool: true on success, false if initialization fails.

Example

Input: (no arguments)
Output: true

load_classifier(classifier_id: GString, directory: GString) -> bool

Load a classifier from a directory on disk.

Inputs

• classifier_id -- logical name to reference this classifier in predict_*.
• directory -- filesystem path to the classifier directory containing model weights and metadata files.

Outputs

bool: true on success, false on error (logged).

Example

Input: classifier_id="sentiment", directory="/models/sentiment_v1"
Output: true

predict_text(classifier_id: GString, text: GString, top_k: i32) -> GString

Predict the class of input text using a loaded classifier.

Inputs

• classifier_id -- the ID passed to load_classifier.
• text -- the input text string to classify.
• top_k -- number of top predictions to include (minimum 1).

Outputs

JSON prediction result (empty string on error):

• label (string) -- predicted class name.
• probability (float) -- confidence score for the top prediction.
• top (array) -- top-k predictions: [{"label": "...", "probability": 0.95}, ...]

Example

Input: classifier_id="sentiment", text="I love this game!", top_k=3
Output: {"label":"positive","probability":0.95,"top":[{"label":"positive","probability":0.95},{"label":"neutral","probability":0.04},{"label":"negative","probability":0.01}]}

predict_image(classifier_id: GString, image_path: GString, top_k: i32) -> GString

Predict the class of an image using a multi-modal classifier.

The classifier referenced by classifier_id must have been trained with an image embedder (e.g. DINOv2). Calling this against a text-only classifier returns an empty string and logs an error.

Inputs

• classifier_id -- the ID passed to load_classifier.
• image_path -- absolute filesystem path to the image file (PNG / JPEG).
• top_k -- number of top predictions to include (minimum 1).

Outputs

JSON prediction result (empty string on error), same schema as predict_text:

• label (string) -- predicted class name.
• probability (float) -- confidence score for the top prediction.
• top (array) -- top-k predictions.

Example

Input: classifier_id="animals", image_path="/abs/path/cat.jpg", top_k=3
Output: {"label":"cat","probability":0.91,"top":[{"label":"cat","probability":0.91},{"label":"dog","probability":0.07},{"label":"bird","probability":0.02}]}

predict_audio(classifier_id: GString, audio_path: GString, top_k: i32) -> GString

Predict the class of an audio clip using a multi-modal classifier.

The classifier referenced by classifier_id must have been trained with an audio embedder (e.g. CLAP). Calling this against a text- or image-only classifier returns an empty string and logs an error.

Inputs

• classifier_id -- the ID passed to load_classifier.
• audio_path -- absolute filesystem path to the audio file (WAV).
• top_k -- number of top predictions to include (minimum 1).

Outputs

JSON prediction result (empty string on error), same schema as predict_text / predict_image:

• label (string) -- predicted class name.
• probability (float) -- confidence score for the top prediction.
• top (array) -- top-k predictions.

Example

Input: classifier_id="sounds", audio_path="/abs/path/bark.wav", top_k=3
Output: {"label":"dog","probability":0.88,"top":[{"label":"dog","probability":0.88},{"label":"cat","probability":0.09},{"label":"bird","probability":0.03}]}

AtelicoKvStoreNode

Godot node for semantic key-value storage with vector similarity search.

Backed by LanceDB. Store text entries with embeddings, then query by vector similarity to find semantically related content. Useful for game dialogue recall, lore lookup, or dynamic context retrieval.

Usage: Add as a child node, call kvstore_create() with a config JSON, then kvstore_query() to search by embedding similarity.

Methods

kvstore_create(config_json: GString) -> bool

Create a new KV store backed by LanceDB.

Inputs

• config_json -- JSON configuration object:
  • store_id (string) -- unique identifier for this store (default "default").
  • db_path (string) -- filesystem path for the database (default "./data").
  • table_name (string) -- database table name (default "entries").
  • embed_dim (int) -- embedding vector dimensionality (default 384).
  • has_priority (bool) -- enable priority scoring (default false).
  • similarity_weight (float) -- weight for similarity in combined score (default 0.5).
  • priority_weight (float) -- weight for priority in combined score (default 0.5).

Outputs

bool: true on success, false on error.

Example

Input: {"store_id":"lore","db_path":"./data/lore","table_name":"entries","embed_dim":384}
Output: true

kvstore_query(store_id: GString, query_json: GString) -> GString

Query a KV store using vector similarity search.

Inputs

• store_id -- the store to query (must match a previous kvstore_create call).
• query_json -- JSON query object:
  • query_embedding (array of float, required) -- the query vector.
  • query_text (string) -- text for display/debug.
  • vector_search_limit (int) -- ANN candidate pool size (default 20).
  • limit (int) -- number of results to return (default 5).
  • use_prefilter (bool) -- apply facet filters before ANN (default true).

Outputs

JSON array of result objects ("[]" on error):

• id (string) -- entry identifier.
• key_text (string) -- entry key text.
• similarity (float) -- cosine similarity score.
• priority (float) -- priority value (if enabled).
• combined_score (float) -- weighted combination of similarity and priority.

Example

Input: store_id="lore", query_json={"query_embedding":[0.1,0.2,...],"limit":3}
Output: [{"id":"1","key_text":"dragon lore","similarity":0.95,"priority":1.0,"combined_score":0.95}]

kvstore_count(store_id: GString, filter: GString) -> i64

Count entries in a KV store, optionally filtered.

Inputs

• store_id -- the store to count entries in.
• filter -- SQL-like filter expression (empty string = no filter, count all).

Outputs

int: the entry count, or -1 if the store is not found or an error occurs.

Example

Input: store_id="lore", filter=""
Output: 42

kvstore_destroy(store_id: GString) -> bool

Delete a KV store and remove it from memory.

Inputs

• store_id -- the store to destroy.

Outputs

bool: true if the store existed and was removed, false if not found.

Example

Input: "lore"
Output: true

kvstore_create_fts_index(store_id: GString, column: GString) -> bool

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

Required before calling kvstore_lexical_query or kvstore_hybrid_query. Typical column choices are "key_text" (the search keys) or any string-typed value column.

Inputs

• store_id -- the store to index.
• column -- column name to index.

Outputs

bool: true on success, false if the store is missing or the indexing call fails.

kvstore_lexical_query(store_id: GString, query_json: GString) -> GString

Lexical (full-text) query against an FTS-indexed column.

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

Inputs

• store_id -- the store to query.

• query_json -- JSON LexicalSearchQuery:

  {"text": "dragon attack", "column": "key_text", "filter": null, "limit": 10}

Outputs

JSON array of KvResult rows ("[]" on error). The combined_score field carries the BM25 score.

kvstore_hybrid_query(store_id: GString, query_json: GString) -> GString

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

Each branch returns up to effective_per_branch_limit candidates; scores are min-max normalised independently and combined with the configured weights. The FTS column must have an FTS index.

Inputs

• store_id -- the store to query.

• query_json -- JSON HybridSearchQuery:

  {
    "embeddings": [0.0, 0.1, 0.2],
    "text": "dragon attack",
    "fts_column": "key_text",
    "filter": null,
    "limit": 5,
    "per_branch_limit": 0,
    "vector_weight": 0.5,
    "lexical_weight": 0.5
  }

Outputs

JSON object on success (empty string on error):

{
  "results": [{ ...KvResult... }],
  "scores":  [{"vector_score": 0.8, "lexical_score": 0.6, "merged_score": 0.7}]
}

AtelicoGuardrailsNode

Godot node for content safety checking (guardrails).

Configure with a preset ("game-safe", "child-safe", or "developer-sdk") and use check_input/check_output/check_image_prompt to validate user or model content against safety policies.

Usage: Add as a child node, call initialize("game-safe"), then pass text through check_input() before sending to the LLM or check_output() before displaying model responses to the player.

Methods

initialize(preset: GString) -> bool

Initialize guardrails with a safety preset.

Inputs

• preset -- one of "game-safe" (default), "child-safe", or "developer-sdk". Each preset configures different thresholds for violence, sexual content, hate speech, etc.

Outputs

bool: true on success, false on error.

Example

Input: "game-safe"
Output: true

check_input(text: GString) -> GString

Check user input text against safety guardrails.

Inputs

• text -- the user-provided input text to validate.

Outputs

JSON SafetyVerdict (empty string on error):

• allowed (bool) -- whether the input passes safety checks.
• category (string, optional) -- violation category (only if blocked).
• reason (string, optional) -- explanation of the violation (only if blocked).

Example

Input: "Tell me a joke about dragons"
Output: {"allowed":true}

check_output(text: GString) -> GString

Check model-generated output against safety guardrails.

Inputs

• text -- the model output to validate before displaying to the player.

Outputs

JSON SafetyVerdict (same schema as check_input, empty string on error):

• allowed (bool) -- whether the output passes safety checks.
• category (string, optional) -- violation category (only if blocked).
• reason (string, optional) -- explanation of the violation (only if blocked).

Example

Input: "The dragon breathes fire at the castle."
Output: {"allowed":true}

check_image_prompt(prompt: GString) -> GString

Check an image generation prompt against safety guardrails.

Inputs

• prompt -- the image generation prompt to validate.

Outputs

JSON SafetyVerdict (same schema as check_input, empty string on error):

• allowed (bool) -- whether the prompt passes safety checks.
• category (string, optional) -- violation category (only if blocked).
• reason (string, optional) -- explanation of the violation (only if blocked).

Example

Input: "A peaceful sunset over mountains"
Output: {"allowed":true}

AtelicoAnnIndexNode

Godot node for approximate nearest neighbor (ANN) vector search.

A pure data structure backed by HNSW (Hierarchical Navigable Small World) graph -- no GPU or ML models required. Insert vectors with label IDs, build the index, then search for nearest neighbors by cosine distance.

Usage: Add as a child node, call create(dim, max_elements), then insert() vectors, call build(), and finally search() to find nearest neighbors.

Methods

create(dim: i32, max_elements: i32) -> bool

Create a new empty ANN index.

Inputs

• dim -- dimensionality of vectors (must match vectors inserted later).
• max_elements -- maximum number of vectors the index can hold.

Outputs

bool: true on success.

Example

Input: dim=384, max_elements=1000
Output: true

insert(vector: Array<f32>, label_id: i64) -> bool

Insert a vector with an associated label ID.

Call build() after all insertions are complete before searching.

Inputs

• vector -- array of floats with length matching dim from create().
• label_id -- integer label to identify this vector in search results.

Outputs

bool: true on success, false if the index has not been created.

Example

Input: vector=[0.1, 0.2, 0.3], label_id=42
Output: true

build() -> bool

Build the HNSW index graph. Must be called after all insertions and before any search() calls.

Inputs

(none)

Outputs

bool: true on success, false if the index has not been created.

Example

Input: (no arguments)
Output: true

search(query: Array<f32>, k: i32) -> GString

Search for the k nearest neighbors of a query vector.

Inputs

• query -- query vector (array of floats with length matching dim).
• k -- number of nearest neighbors to return.

Outputs

JSON array of result objects sorted by ascending distance ("[]" if index not created):

• label_id (int) -- the label assigned during insert().
• distance (float) -- cosine distance (lower = more similar).

Example

Input: query=[0.1, 0.2, 0.3], k=3
Output: [{"label_id":42,"distance":0.05},{"label_id":17,"distance":0.12},{"label_id":8,"distance":0.34}]

AtelicoEmbedderNode

Godot node for direct multimodal embedding (text, image, audio).

Wraps the SDK embedding subsystem to turn a string, an image file, or an audio file into a dense vector. The three modalities can share one space when a cross-modal model embeds them, so a text query can retrieve images or audio by cosine similarity (feed the vectors into [AtelicoAnnIndexNode]).

Model id convention

Pass the embedder model id (optionally "in-memory::"-prefixed) for the modality you are embedding:

• Text — a BERT-family encoder, e.g. "bge-small-en" / "in-memory::bge-small-en" (384-dim).
• Image — a vision encoder or cross-modal image tower, e.g. "dinov2-small" (the DINOv2-Small vision embedder, 384-dim), "dinov2-large", "clip", "siglip".
• Audio — the CLAP audio tower, "clap".

Gating

Each embed_* call resolves the model from the on-device cache and never triggers a blocking download: if the weights are absent it logs an error and returns an empty PackedFloat32Array. Gate first with AtelicoEngineNode.is_model_cached(model) and, if missing, fetch via AtelicoEngineNode.model_download_async(model, token) before embedding.

Usage: Add as a child node, call initialize(), then embed_text() / embed_image() / embed_audio().

Methods

initialize() -> bool

Initialize the embedding engine. Must be called before any embed_*.

Inputs

(none)

Outputs

bool: true on success, false if initialization fails.

embed_text(model: GString, text: GString) -> PackedFloat32Array

Embed a text string into a dense vector.

Inputs

• model -- text embedder model id (e.g. "bge-small-en").
• text -- the text to embed.

Outputs

PackedFloat32Array: the embedding vector, or empty on error or when the model is not cached (see the node-level gating contract).

Example

Input: model="bge-small-en", text="a friendly dragon"
Output: [0.012, -0.034, 0.056, ...]  (384 floats)

embed_image(model: GString, image_path: GString) -> PackedFloat32Array

Embed an image file into a dense vector.

Inputs

• model -- image embedder model id (e.g. "dinov2-small").
• image_path -- absolute filesystem path to a PNG/JPEG file.

Outputs

PackedFloat32Array: the embedding vector, or empty on error or when the model is not cached.

Example

Input: model="dinov2-small", image_path="/abs/path/creature.png"
Output: [0.21, -0.08, 0.13, ...]  (384 floats)

embed_audio(model: GString, audio_path: GString) -> PackedFloat32Array

Embed an audio file into a dense vector.

Inputs

• model -- audio embedder model id (e.g. "clap").
• audio_path -- absolute filesystem path to a RIFF/WAVE file.

Outputs

PackedFloat32Array: the embedding vector, or empty on error or when the model is not cached.

Example

Input: model="clap", audio_path="/abs/path/bark.wav"
Output: [0.04, 0.17, -0.02, ...]  (512 floats)

AtelicoCacheNode

Godot node for prompt result caching.

Methods

initialize() -> bool

cache_get(key_json: GString, policy_json: GString) -> GString

Look up a cached result. Returns JSON or empty string on miss.

cache_put(key_json: GString, policy_json: GString, response_json: GString) -> bool

Store a result in the cache.

cache_clear()

cache_size() -> i32

AtelicoMatcherNode

Godot node for ranking candidates against a query.

Methods

initialize() -> bool

match_one(matcher_id: GString, query: GString, elements_json: GString) -> GString

Match the single best candidate. Returns JSON or empty string.

VectorMemoryStore

Godot node for vector memory storage backed by LanceDB.

Stores character memories and metadata as vector-embedded records and supports similarity-based retrieval. Useful for NPC memory recall, narrative context, and character persona management.

Usage: Add as a child node, set db_name and embed_dim exports, then call connect_to_db() and get_or_create_table() before reading or writing records.

Methods

connect_to_db(db_name: GString) -> bool

Open (or create) a LanceDB database at user://database/ followed by db_name. Does not create tables -- call get_or_create_table afterwards to set up tables with the desired schema.

• db_name: database directory name (e.g. "npc_memories").

Returns: true on success, false if the connection fails or the database is already connected with the same name.

get_or_create_table(table_name: GString, table_schema: GString) -> bool

Open or create a table with the given schema name. If the table already exists, it is opened; otherwise a new table is created with the specified schema.

• table_name: logical table name (e.g. "npc_observations").
• table_schema: schema preset name. Composable convention: "memory", "memory+emotion", "character", "character+emotion".

Returns: true on success, false if not connected or on error.

write_memory(_table_name: GString, node: VarDictionary) -> bool

Write a single memory record to the store.

• _table_name: reserved for future multi-table support (currently unused).
• node: a Dictionary containing all Memory fields. Required keys: uuid, observer, counter, node_count, type_count, depth, poignancy, node_type, embedding_key, location, created, expiration, subject, predicate, object, description, filling (Array of String), and vector (Array of float with length matching embed_dim). Optional: emotion_at_encoding (String).

Returns: true on success, false if not connected or the dictionary is missing required fields.

write_character(_table_name: GString, character: VarDictionary) -> bool

Write a single character/persona metadata record to the store.

• _table_name: reserved for future multi-table support (currently unused).
• character: a Dictionary containing character fields. Required keys: uuid, uuid_int, persona_name, age, personality, background, story, daily_plan, home, lifestyle, usual_wake_up_time, activity, reflectiveness. Optional: emotional_baseline (String, defaults to "neutral").

Returns: true on success, false if not connected or the dictionary is missing required fields.

get_table_row_count(_table_name: GString, filter: GString) -> i64

Count rows in the memory store, optionally filtered.

• _table_name: reserved for future multi-table support (currently unused).
• filter: SQL-like filter expression (empty string means count all rows).

Returns: the number of matching rows, or -1 if not connected or on error.