# ===========================================================================
# LLM Connect — Luanti Mod Settings
# ===========================================================================
# Version: 1.3.0
# ===========================================================================


# === API Connection ===

llm_api_key              (API Key)                                    string
llm_api_url              (API URL – OpenAI-compatible endpoint)       string
llm_model                (Model name)                                 string

llm_max_tokens           (Max tokens – response length)               int    4000   500   16384
llm_max_tokens_integer   (Send max_tokens as integer)                 bool   true

llm_temperature          (Temperature – creativity, 0..2)             float  0.7    0.0   2.0
llm_top_p                (Top P – nucleus sampling, 0..1)             float  0.9    0.0   1.0
llm_presence_penalty     (Presence penalty, -2..2)                    float  0.0   -2.0   2.0
llm_frequency_penalty    (Frequency penalty, -2..2)                   float  0.0   -2.0   2.0

# Enable verbose API request/response logging to the server log.
llm_debug                (Enable debug logging)                       bool   false

# Write raw LLM request/response payloads to world-local trace files.
# Files: llm_user_prompt_log.txt and llm_response_prompt_log.txt in the world directory.
# WARNING: very verbose. Prompt content may contain private data. Authorization headers are not logged.
llm_trace_prompt_log    (Trace raw LLM request/response payloads to world files) bool false


# === Timeouts ===

# Timeout in seconds for every LLM HTTP request (chat, IDE, agent — one
# setting controls all of them; there is no per-mode override). Also
# editable in-game via the config GUI's API tab, which now persists here.
llm_timeout              (Global request timeout in seconds)          int    120    30    600


# === Chat ===

# Optional system prompt injected into every plain chat request (non-agent mode).
# Leave empty for no system prompt — basic_context (player pos, commands etc.)
# is always included separately regardless of this setting.
# Example: "You are a helpful Luanti server assistant. Answer briefly."
llm_chat_system_prompt (Chat mode system prompt, empty=none)         string

# Max number of messages from chat history sent per LLM request.
# Oldest messages are dropped first when the limit is exceeded.
llm_context_max_history  (Max chat history messages sent per request) int    20     2     100

# Persist chat history (and the chat list) across relogs and server restarts.
# Server-wide kill switch. Even when true, individual players can still be
# opted out per-player from the Agent tab in the config GUI (llm_root only).
llm_chat_history_persist (Persist chat history across sessions) bool true

# Hard cap on messages kept per chat when persisting to disk. Oldest
# messages are truncated first. Does not affect in-memory history during
# an active session — only what gets written to disk.
llm_chat_history_max_entries (Max persisted messages per chat) int 200 10 2000


# === Language ===

# LLM response language. "en" injects no language instruction (saves tokens).
# All other values prepend a language instruction to each request.
llm_language             (Response language)                          enum   en   en,de,es,fr,it,pt,ru,zh,ja,ko,ar,hi,tr,nl,pl,sv,da,no,fi,cs,hu,ro,el,th,vi,id,ms,he,bn,uk

# How many times to repeat the language instruction per request.
# Increase to 2–3 if the model keeps switching back to English.
llm_language_instruction_repeat (Repeat language instruction N times) int    1      0     5


# === Agent ===

# Master switch — disables all agent runs server-wide when false.
# Individual players also need the llm_agent privilege to use the agent.
# Useful to temporarily lock down agency on public servers without revoking privileges.
llm_agent_enabled        (Enable agent mode globally)                 bool   true

# Maximum number of LLM iterations per agent run.
# The agent stops when the LLM signals done=true, hits a hard error, or
# reaches this limit.
llm_agent_max_iterations (Max agent loop iterations)                  int    8      1     32

# Maximum number of repair iterations after failed lua_action execution.
# 0 disables repair retries. This is separate from llm_agent_max_iterations:
# every repair retry still consumes one normal agent loop iteration.
llm_agent_max_repair_retries (Max failed-action repair retries)       int    1      0     10

# Root-only escape hatches for local owner/developer workflows. Keep disabled
# on public servers unless you fully trust every llm_root user.
llm_root_agent_unrestricted       (Allow llm_root agent actions to run unrestricted) bool false
llm_root_bypass_safety_filters    (Allow llm_root to bypass Lua precheck host-access filters) bool false
llm_root_allow_startup_execution  (Allow llm_root to execute startup-preferred code transiently) bool false

# Root-only live trace stream into the in-game chat log. This is for active
# development/debugging and can be noisy. Raw Lua action display is separate.
llm_live_trace_chat       (Stream LLM Connect debug trace to root chat) bool false
llm_live_trace_show_lua   (Include raw lua_action code in live trace) bool false
llm_live_trace_verbosity  (Live trace verbosity) enum normal quiet,normal,verbose
llm_live_trace_categories (Live trace categories, comma-separated or all) string all


# === Smart Lua IDE ===

# IDE Save writes to <worldpath>/llm_scripts/<player>/scripts/.
# Saved *.lua files are cold-loaded on the next server/world start.

# Deprecated / not implemented in the current Lua-first IDE.
# Kept only so old minetest.conf entries remain documented.
llm_ide_auto_save              (DEPRECATED: Auto-save code buffer on changes) bool  false

# Deprecated policy anchor. Current runtime policy always keeps llm_dev
# sandboxed; llm_root behavior is controlled by the root settings above.
llm_ide_whitelist_enabled      (Scope llm_dev to sandboxed execution)         bool  true

# Deprecated / not implemented in the current Lua-first IDE.
llm_ide_live_suggestions       (DEPRECATED: Live AI suggestions while typing) bool  false

# Send the last run output to the LLM in Generate and Auto-Fix calls.
# Allows the model to see errors and output from the previous execution.
llm_ide_include_run_output     (Include last run output in LLM context) bool  true

# Max lines of code sent as context in Generate calls.
# Prevents token overflow on large files. 0 = no limit.
llm_ide_max_code_context       (Max code lines sent to LLM, 0=no limit) int  300    0    2000

# Max Auto-Fix iterations after a failed run. 0 = Auto-Fix disabled.
# Each iteration calls the LLM once to fix the error and re-executes.
llm_ide_auto_fix_iterations    (Auto-Fix max iterations, 0=off)        int   3      0    10

# Inject a naming-convention guide into Generate calls.
# Adds general Luanti registration naming guidance without forcing llm_connect:.
llm_ide_naming_guide           (Inject registration naming guide)     bool  true

# Include the active mod list in IDE Generate context.
llm_ide_context_mod_list       (Send mod list in IDE context)           bool  true

# Include player position in IDE Generate context.
# Useful for position-aware code generation (e.g. placing nodes near the player).
llm_ide_context_player_pos     (Send player position in IDE context)    bool  true

# Default API reference injection level when the IDE is opened.
# Can be toggled live per-session in the IDE toolbar.
#   none – no reference (default, lowest token cost)
#   slim – ~400 tokens: most-used functions
#   full – ~2000 tokens: comprehensive (use sparingly)
llm_ide_api_default_level      (Default API reference level)            enum  none  none,slim,full

# Maximum number of assets that can be selected at once in the IDE Asset Picker.
llm_ide_asset_max_selected     (Max assets selectable in IDE picker)    int   32     1    128


# ===========================================================================
# Notes:
#
#   llm_language:
#     "en" injects no instruction and saves tokens. For non-English output,
#     set to the desired language code; increase llm_language_instruction_repeat
#     if the model ignores the instruction.
#
#   llm_ide_api_default_level:
#     "full" should only be used for complex generation tasks — it adds
#     ~2000 tokens to every Generate call. Prefer "slim" or "none" and
#     enable "full" per-session in the IDE when needed.
#
#   Runtime changes:
#     API key, URL, model, and timeout can be tweaked at runtime via the
#     config GUI's API tab (/llm_config) without a server restart — but
#     this is session-only and does NOT write back here. This file (or
#     minetest.conf) stays the persistent source of truth; the GUI only
#     overrides the in-memory value for the current server run. All other
#     settings below are edited here directly and need a restart or
#     /llm_config_reload to take effect.
#
# ===========================================================================
