ВЕРСИИ (8)

# NSR-AI v1.5 — Stability & Performance Update > **Plugin Version:** 1.5  |  **API Version:** 3.5  |  **Build Status:** Verified (v1.5-PRODUCTION) NSR-AI v1.5 is a major optimization release focused on turning the core engine into a faster, more stable system. Where v1.4 focused on features, v1.5 focuses on **stability, speed, and reliability**. We reviewed the codebase to cut technical debt, hardened the API pipeline against network errors, and moved to modern Java standards so your server stays responsive even under heavy AI load. --- ## 📋 Quick Summary | Area | Improvements | |---|---| | ⚡ **Optimization** | Reduced object churn; pre-compiled logic for lower-latency chat | | 🛡️ **Stability** | Legacy code review; thread-safe date handling; null-safe API pipeline | | 🔌 **API Pipeline** | Fixed Claude system role protocol; added Gemini safety guards; key fallback resilience | | 🏗️ **Architecture** | Modular refactor; decoupled pets, config, and error logging | | 📜 **Logging** | Human-readable error messages with actionable suggestions for server owners | --- > [!IMPORTANT] > **Critical Google API Update (Applies to v1.3, v1.4, & v1.5)** > * **Google `AQ.` API Key Support**: Added full support for Google's new `AQ.` API key prefix alongside the legacy `AIza` format, ensuring compatibility with newer service keys issued by Google AI Studio. > > *Note: This new Google prefix also applies to NSR-AI **v1.3** and **v1.4** plugins. If the plugin is already downloaded, you just have to restart the server to reflect these changes.* --- ## ✨ New Features & Enhancements ### 📡 In-Game Version & Changelog Viewer *(New in v1.5)* Players and admins can now view live, version-specific changelogs directly in-game, without visiting the website or wiki. - **`/ai version`**: Displays the currently running plugin version alongside its full, formatted changelog, fetched asynchronously from the remote manifest so the server thread is never blocked. - **`/ai version bug`**: Shows the bug fix module changelog pinned to the current plugin version. If you're running plugin `v1.4` with bug module `v1.0`, you'll see the `v1.4`-specific `v1.0` bug changelog, not the latest bug version's changelog. Fully version-isolated. - **`/ai version security`**: Displays the security module version and its own dedicated changelog, since the security module operates independently across all plugin versions. - **Async Fetching**: All three sub-commands fetch from the remote `worker.json` manifest on a background thread and deliver the result back on the main thread, avoiding server lag during lookups. - **Cache-First Design**: Subsequent calls return instantly from an in-memory cache; the network hit only occurs on the first lookup per server session. ### 🛡️ Dual Management Architecture We've introduced a clearer separation between internal addons and external API consumers for cleaner administrative control: - **Dedicated Addon Manager (`/aia addon`)**: Now exclusively handles `.jar` files in the `addons` folder with a new summary system (Total, Active, Error/Banned, and Inactive counts). - **API Bridge Inspector (`/aia plugin`)**: A new command system to track and inspect external plugins that have hooked into NSR-AI via the API. ### 🔍 Integration Analytics - **Full Plugin Details**: Administrators can now use `/aia plugin [name]` to retrieve metadata from external integrations, including Author, Version, and Project Descriptions. - **Context-Aware Tab Completion**: The command system now filters suggestions based on the management category, so subcommands only appear for relevant addons or plugins. ### 🤖 In-Built System Prompt Improvements - **Ecosystem-Aware Identity**: NSR-AI now uses a more detailed system prompt containing comprehensive details about the plugin, its features (including API key fallbacks, RAG local searches, active conversation memory, and live AI pets), and command structures. - **Anti-Override Guard**: The system prompt enforces rules to prevent players from bypassing or overriding its core Minecraft companion identity, so it behaves reliably as a server assistant while ignoring prompt injection attempts. ### 📦 NSR-AI-API 3.5 Open-Source API Features - **Facade Delegation Architecture & Clean Root Package**: Routes legacy V1/V2 API calls to V3 endpoints. All 8 legacy classes (`AIMessage`, `AIResponse`, `AddonInfo`, etc.) have been moved into a dedicated `com.nsr.ai.api.v1` package, keeping the root API directory clean while `NSRAI.java` serves as the sole deprecated bridge. - **Dynamic Pet Stat Manipulation**: Programmatically modify pet attributes (`Bond`, `Mood`, `Hunger`, `Level`, `Health`) to build custom pet training or RPG integrations. - **Asynchronous Chat Interceptor Pipeline**: Register interceptors (`AIInterceptor`) to inspect, sanitize, modify, or cancel player inputs, AI responses, and system prompts. - **Asynchronous Error Catcher Pipeline**: Register error handlers (`ErrorCatcher`) to passively monitor, actively modify, or suppress AI API and runtime errors before they reach the player. - **Granular AI Request Parameters**: Programmatically inject custom provider settings (`Temperature`, `Top-P`, `Top-K`, `Max Tokens`, `presence_penalty`) per individual AI request. - **Live Knowledge Base Bridge (RAG)**: Dynamically read, inject, or remove vector knowledge base entries directly from active server memory. - **Universal Command Routing (`/aia`)**: Delegate complex subcommands and tab completions directly to your addon or plugin integration. - **Non-Blocking Persistence (`SaveMsg`)**: Asynchronously save addon data in JSON, YML, TXT, or DAT formats without blocking the primary server thread. - **Native Plugin Integration Builder (`SimpleAddon`)**: Standard Bukkit plugins can now natively register as NSR-AI integrations without needing an `addon.yml` manifest. --- ## ⚡ Stability & Optimization We re-engineered the plugin's hot paths so that AI processing has minimal impact on your server's Tick Rate (TPS). ### 🚀 Reduced-Allocation Regex Previously, the plugin re-compiled complex text-processing patterns every time a player chatted. - **Pre-Compiled Patterns**: We've implemented 12+ static final patterns for error codes, code snippets, and log parsing. This removes a large number of object allocations per minute. - **Matcher Reuse**: High-frequency methods like `filterCodeSnippets` and `refineResponse` now reuse matchers, reducing CPU spikes. ### 🧵 Modern Thread-Safety - **SimpleDateFormat → DateTimeFormatter**: We've replaced all non-thread-safe legacy date formatters with modern Java `DateTimeFormatter`. This removes the risk of silent crashes or corrupted dates during high-concurrency async operations. - **Concurrent Structures**: All remaining internal maps have been audited to ensure they use proper concurrency controls, preventing `ConcurrentModificationException` during heavy API rotation. ### 📦 Codebase Cleanup - **Codebase Consolidation**: Removed redundant "skeleton" code and legacy artifacts, resulting in a cleaner, more maintainable plugin core. ### 🧩 Modular Architecture - **Code Decoupling**: The main class has been broken up into smaller, focused components. - **Dedicated Managers**: Core logic has been offloaded into dedicated, specialized subclasses to improve maintainability and speed up future updates: - **`ConfigManager`**: Centralized all configuration fields, prefixes, and messages. - **`PetSystem`**: Encapsulates all AI Pet logic, including personality prompts and mood management. - **`ErrorLogger`**: Standardized error handling, translating technical codes into human-readable advice. - **`KnowledgeManager`**: Handles knowledge base orchestration and automated heading generation. - **`ApiKeyManager`**: Orchestrates model resolution and retry logic across multiple providers. - **`MemoryManager`**: Isolates conversation history tracking and automated memory refresh cycles. - **`HelpCommand`**: Decoupled all detailed help formatting, isolating menu layouts and resolving chat vulnerabilities. ### 🔌 API Pipeline & Resilience The connection between your server and AI providers (Gemini, Claude, OpenAI) is now more robust. #### 🤖 Provider-Specific Hardening - **Claude System Role Fix**: Corrected a protocol bug where system instructions were being sent incorrectly. Claude now correctly respects the top-level `system` prompt field for better identity stability. - **Gemini Safety Guard**: Implemented mandatory `candidates` presence checks. This prevents the plugin from throwing cryptic JSON errors if the AI returns an empty or filtered response. - **Automatic Key Failover**: Background tasks like "AI Heading Generation" now automatically rotate through all available active keys if one fails, so your knowledge base stays up to date. #### 🛠️ Diagnostic Error Handling Server owners now get clearer, actionable feedback when things go wrong. Instead of raw technical logs, you'll see messages like: - `[NSR-AI] Error 401: Invalid API Key. Suggestion: Please check your key in the config.` - `[NSR-AI] Error 429: Rate Limit Exceeded. Suggestion: This key is temporarily disabled to prevent further errors.` --- ## 🐛 Bug Fixes & Code Hardening We carried out a thorough audit resolving a number of bugs, logic exceptions, and structural edge cases across the plugin codebase. ### 🔴 Critical Bug Fixes * **Global API Key Rotation**: Implemented true round-robin rotation for global API keys to evenly distribute player loads. * **Startup NPE Resolution**: Reordered plugin enablement phase to prevent NullPointerExceptions during early manager checks. * **AIA Command Restoration**: Restored routing logic for `/aia` commands, resolving registration failures for community addons. * **Addon Path Hardening**: Added validation checks to catch corrupt or invalid JAR paths during filesystem scans. * **Command System Protection**: Guarded API key commands against NullPointerExceptions when UUID configurations are missing. * **Memory Leak Resolution**: Ensured player cooldowns and request context caches are properly cleared on disconnect. * **Context Limit Restoration**: Restored support for players to dynamically adjust their context parameters via chat. * **API Protocol Correction**: Corrected Anthropic API JSON formatting to prevent Claude from ignoring system instructions. * **Help Command Truncation**: Refactored Spigot packet transmissions to deliver help text line-by-line rather than in a single bloated packet. * **Asynchronous Chat I/O Fix**: Offloaded the expensive `getChatEntry` disk-read loop to async worker threads to eliminate lag. * **Double Loading I/O**: Resolved redundant file reads in `/ai chat list` commands by utilizing in-memory caches. * **Persistence Trick Fix**: Replaced a code smell in `/ai apikey timer` with an explicit key-save delegate method. * **Decompiler Variable Cleanup**: Removed dead decompiler artifacts and streamlined conditional switch branches. * **Color Constant Optimization**: Declared static final ChatColor strings to prevent repetitive runtime evaluations. * **Thread-Safe Async Message Dispatch**: Guided player notification messages from the async chat event to the main server thread. * **Offline Owner NPE Guard**: Added online checks to tamer UUID lookups in pet share link usages to avoid crashes. * **Shared Pet Link Preservation**: Prevented pet link queries from prematurely deleting active link states. * **API Key Leak Security**: Instantly cancels player chat events before key validation to prevent keys from leaking to public chat. * **Deterministic Pet Link Routing**: Implemented relationship checks instead of length matches for pet link subcommands. * **Main Thread Network I/O**: Replaced synchronous Mojang name queries in `/pet` commands with cached in-memory profiles. * **Hidden Admin Command Try-Catch**: Wrapped UUID queries in pet confirm commands to prevent uncaught exceptions. * **Inventory Authorization Guard**: Enforced strict ownership checks on `/ai pet inv allow` to block unauthorized modifications. * **Version Banner Formatting**: Restored context headers and player version indicators in update alerts. * **Constant-Time Admin Check**: Replaced standard string equality comparison on the admin key with a constant-time check to prevent side-channel timing attacks. * **RAG Context Skipping Fix**: Ensured RAG search context is injected even if the core question is identical to the user query. * **Top-3 Match Limit**: Restricted relevance query retrieval to the top 3 items to optimize prompt token usage. * **Dual-Mode Offline Notification**: Upgraded notifications to report whether an API key failed or was missing before showing offline matches. * **Conversation History Filter**: Automatically strips large RAG knowledge blocks from conversation history logs before writing to disk. * **Unlink Null-Check Reordering**: Placed pet null checks prior to owner lookup checks to prevent logical errors. * **Paginated Bulk Knowledge Dump**: Implemented pagination (5 entries per page) for `/ai data all` to prevent console stuttering. * **Commands Dead Code Scrub**: Removed unreachable bypass check conditions from knowledge command handlers. * **Fragile Keyword Extraction**: Replaced keyword substring splitting with a direct index slice to support keywords containing the word "add". * **Double-Pipe Delimited Key Confirmations**: Replaced fragile null byte separators with safe double-pipe strings for pending confirmation payloads. * **Bypass Expiry Enforcement**: Added a strict timestamp expiration loop to expire pending confirmations after 60 seconds. * **Reload Authorization Guard**: Restructured reload commands to verify administrative rights before reload executes. * **Tab Completion Network I/O**: Cached player names in a local cache to avoid main-thread Mojang lookups during command typing. * **O(N×M) Tab Completion Cache**: Cached pet tab completion suggestions for 2 seconds to prevent double-loop collections iteration spikes. * **Subcommand Tab Completer Decoupling**: Isolated chat subcommand complete checks into distinct conditional branches. * **Cooldown Early Return Feedback**: Added warning feedback for players who attempt to click AI response regeneration inside the cooldown window. * **Config Persistence for Context & AutoSummary**: Fixed a bug where player context limits and auto-summary parameters were only updated in memory and never saved. * **RAG Pipeline Data-Loss Fix**: Unified RAG composite key delimiters to `"/"` to prevent silent array index exceptions during save. ### ⚡ Stability & Optimization * **Pre-Compiled Patterns**: Implemented 12+ pre-compiled static final regex patterns to eliminate repeated pattern compilation heap allocations. * **DateTimeFormatter Upgrade**: Swapped legacy `SimpleDateFormat` with modern Java `DateTimeFormatter` to ensure thread-safe concurrent log formatting. * **Switch Expressions Migration**: Replaced legacy if/else chains with clean, arrow switch statements to eliminate fall-through risks. * **Pattern Matching instanceof**: Utilized modern pattern matching `instanceof Player player` casts to simplify code structure. * **Immutable List Optimizations**: Swapped raw array creations with modern immutable `List.of()` lists. * **Key Manager Cache**: Stored repeated API manager calls into local context variables to reduce getter depth. * **Collections Qualification Scrub**: Cleaned up full-package concurrent collections qualifiers in favor of standardized package imports. * **Command Redundancy Audit**: Pruned redundant decompiler casting strings and duplicate import statements. * **Random Generation Caching**: Statically cached `SecureRandom` and character buffers to avoid continuous heap allocations. * **Folder Creation Guard**: Fixed a bug where the plugin would mistakenly create an empty `addons` directory on command execution. * **Session Expiration Guards**: Implemented timer loops to expire session inputs after periods of player inactivity. * **Modern Event Migration**: Migrated chat hooks to `AsyncPlayerChatEvent` for compatibility with newer Spigot builds. * **Memory Refresh Correction**: Restored proper historical summarization when manually invoking conversation restarts. * **Null Safety Audit**: Hardened the entire pipeline against null player references and uninitialized API configurations. ### 🛡️ Security & Privacy Hardening * **Overloaded Key Logger Masking** *(New)*: Fixed a security leak present in v1.3 where raw global API keys were printed verbatim in console rate-limit warning messages. Keys are now securely masked, displaying only the last 4 characters (e.g. `***xxxx`), preventing accidental key exposure in server logs or shared console recordings. * **Secure /ai apikey add Command**: Shifted API key submissions to a dedicated command intercepted at the highest priority to avoid console logging. * **Encryption Key Permissions**: Restricted OS permissions on encryption secret, salt, and master key files to owner-only read/write. * **Bounded LRU Crypto Cache**: Replaced the unbounded concurrent key cache with a bounded LRU cache (max 512) to prevent memory leaks. * **Hashed Crypto Cache Keys**: Hashed cached master keys via SHA-256 instead of caching raw player UUIDs in memory. * **Fatal Crypto Failure Guard**: Configured the plugin to disable itself cleanly if JVM cryptographic providers fail to initialize on startup. * **Config List Encryption Abort**: Aborts configuration list encryption if any single item fails, preventing corrupted config saves. * **SHA-256 Digest Caching**: ThreadLocal-cached SHA-256 digest instances to avoid repeated provider lookups. * **Insecure Legacy EncryptionUtil Removal**: Deleted outdated cryptography utilities that cached raw secrets in memory. * **MessageFormatter Thread Safety**: ThreadLocal-cached date formatters inside the chat display module to prevent concurrent date corruption. * **UpdateChecker Connection Safeguards**: Enforced semantic version comparison and connection timeouts on remote update checks. * **ChatLogger Session Timeout & Storage**: Batched log writes per file, masked API keys asynchronously, and evicts entries on player quit. * **SecurityManager Integrity Verification**: Added SHA-256 checksum checks to remote JAR downloads before classloading execution. * **SecurityManager Thread Dispatching**: Guided dynamic classloader reloads onto the main Bukkit thread to comply with Bukkit API rules. * **SecurityManager Atomic Swapping**: Implemented thread-synchronized atomic swapping for URL classloaders during live reloads. * **SecurityManager Uninitialized Guard**: Prevents cyclic updater restarts if the initial JVM classload of the security JAR fails. * **Explicit Addon Blocking Warning**: Added diagnostics logging when addon validation fails due to uninitialized security states. * **SecurityManager Dead Code Removal**: Cleaned up unreferenced updater variables and finalized remote manifest mapping fields. ### 🐾 Pet & RAG System Improvements * **Enhanced Pet AI System Prompt**: Designed dynamic, multi-tiered prompt instructions with expressive emoji accents and relationship dynamics. * **Knowledge Base Prompt Improvements**: Implemented multi-line text block prompts for factual heading extraction and intent decoding. * **Master System Prompt Rework**: Constructed a default ecosystem instructions prompt with guards against administrative prompt injection overrides. * **Markdown-to-Minecraft Rich Text Formatter**: Built a parsed Spigot utility to format horizontal dividers, code blocks, lists, and headers in chat. * **Non-Spammy Action Bar Thinking Animation**: Relocated the AI thinking notification to the player's action bar to prevent chat log clutter. * **Gemini System Prompt Reinforcement**: Injects system prompts on every conversational turn to prevent personality drift. * **Intelligent Past Summary Integration**: Dynamically injects past conversation summaries with transition directives to guide topic changes. * **Simplified Affectionate Pet Prompt**: Restructured pet dialogues to use brief sentences and young, emotional expressions. * **Modular System Prompt Bypass**: Implemented a programmatic skipSystemPrompt flag for pets, RAG, and memory tasks to avoid identity leaks. * **Knowledge Base JSON Migration**: Converted the knowledge base file format from YAML to JSON to support concurrent reads and bypass key separator bugs. * **Automated Data Upgrader**: Added a migration command (`/ai migrate`) to convert legacy knowledge databases with backups. * **Atomic AI Knowledge Generation**: Leverages a single atomic API call to format raw inputs into headings and content. * **RAG Search Order Loss Fix**: Swapped hash maps with LinkedHashMaps inside relevance sorting to keep the highest matches first. * **RAG Score Collision Fix**: Used score merging instead of direct replacement to correctly accumulate relevance scores across maps. * **Null Heading Fallback Guard**: Added fallback guards to prevent empty API responses from writing literal nulls to keys. * **Unused Iterator Import Cleanup**: Removed unreferenced class imports from knowledge management files. * **Pig Death Broadcast Restriction**: Restricts Pig tribute messages to the pet owner instead of broadcasting to the server. * **Index-Preserved Saved Chat Deletion**: Implemented checkpoint deletion tombstones to prevent list offsets during checkpoint resumes. * **Double File Deletion Safeguards**: Synchronized file system purges to ensure checkpoints are fully deleted before directory cleanup. * **Active Lazy Loading Chat Trigger**: Automatically registers loaded chat history checkpoints into active memory. * **Secure Non-Colliding Random Codes**: Enforced secure alphanumerical generation checks to ensure anonymization tokens never overlap. * **Synchronized File Write Locks**: Wrapped chat deletions in synchronizations to protect disk operations from thread overlap. * **Atomic Settings Cache Evictions**: Replaced separate map checks with atomic evictions to secure player configuration modifications. * **Clarified Sequential Privacy Locks**: Rewrote privacy switches to perform configuration writes outside of class locks. * **Saved Chat Formatted Timestamp Cache**: ThreadLocal-cached SimpleDateFormat wrappers to optimize historical chat time formats. * **Pruned Dead saveAllChats Hooks**: Deleted empty shutdown hooks and unreferenced save logs. ### 🔌 Addon & Command Integrations * **Facade Delegation Architecture**: Moved all legacy classes into a dedicated V1 package, routing legacy requests to modern facades. * **Dynamic Pet Stat Manipulation**: Programmatically exposes setters for pet bond, level, mood, hunger, and health. * **Asynchronous Chat Interceptor Pipeline**: Exposes registers for AIInterceptor addons to inspect, edit, or cancel chat streams. * **Asynchronous Error Catcher Pipeline**: Registers custom handlers to catch and format API errors before they reach players. * **Live Knowledge Base Bridge (RAG)**: Programmatically injects or removes local knowledge entries directly from memory. * **Universal Command Routing (/aia)**: Routes delegated addon commands and tab completions directly to addon files. * **Non-Blocking Persistence (SaveMsg)**: Decoupled addon file writes into asynchronous background worker tasks. * **Native Plugin Integration Builder (SimpleAddon)**: Exposes a builder-pattern class allowing standard Bukkit plugins to register. * **Addon Deprecation Annotation**: Appended @since annotation tags to deprecated addon models. * **Addon Loading listFiles() Null Safeguard**: Guarded addon scans against empty directories to prevent startup crashes. * **Lifetime Kept-Open Addon ClassLoader Mapping**: Maintained a persistent classloader index map to prevent ClassNotFound exceptions on runtime reloads. * **Duplicate Addon Load Detection Guard**: Instantly skips duplicate addon JARs and namespace conflicts on startup. * **Double JAR-File Open Optimization**: Direct ClassLoader resource stream queries bypass OS file locking issues. * **Comprehensive Throwable Capture**: Captures setup throws to safely close open addon jars. * **Stale Player Identity Protection**: Caches player UUIDs instead of storing active player references in async threads. * **Completion Future Hang Protection**: Completes future threads even if players log off mid-request. * **Atomic Cooldown Map Queries**: Replaced multi-step queries with atomic concurrent gets to prevent cooldown bypasses. * **Thread-safe System Prompt Lock**: Synchronized player history reads during system prompt insertion. * **Try-Finally Thinking Animation Cleanup**: Guarantees thinking animation cessation on all unhandled thread exceptions. * **Stale Completed Conversations Eviction**: Evicts finished conversations older than 10 minutes to prevent memory bloat. * **Redundant UUID Typecast Cleanups**: Removed unnecessary casting strings in commands. * **ReservedNicknameManager Synchronized Reads**: Synchronized nickname reservations to avoid duplicate assignments. * **Asynchronous ReservedNickname Saves**: Asynchronously saves name configurations to disk. * **Pet Attribute Range Clamping**: Enforces bound checks on level, bond, hunger, and health. * **Thread-safe Lazy Pet Mention Pattern**: Synchronized pet mention patterns compiled at runtime. * **SharedPetLink Expiration Redundancy**: Simplified pet friendship check calculations. * **Pet Subfolder Creation Guard**: Ensures new player directories are created before saving pet properties. * **Directory listFiles() Null Safeguards**: Safe arrays check on pet file loadings. * **ThreadLocal Chat Logger Caches**: Optimized date format operations. * **Pet Death Log generics**: Replaced raw mappings with type-safe generic lists. * **Predictable Random Link Code Fix**: Replaced Predictable Random with SecureRandom and recursion with loops to avoid StackOverflows. * **Pet Relationship Map UUID Keys**: Swapped integer index keys with UUID strings to keep friends intact across reboots. * **Dynamic Argument Subcommand Routing**: Offsets subcommand indexes dynamically to support standalone pet commands. * **Double Map Lookup Optimization**: Streamlined lookup performance in pet linking commands to retrieve friend metadata in a single `.get()` call rather than executing repetitive `.contains()` mappings. * **Random Generation Caching**: Optimized random alphanumeric string generations by statically caching `SecureRandom` and character arrays to avoid continuous heap allocations. * **Addon Security Audit**: Implemented several permission checks (including `nsrai.admin`) for sensitive addon management commands to protect server information. * **Folder Creation Guard**: Fixed a logical error where the plugin would unexpectedly create an `addons` folder during command execution. * **Session Expiration Guards**: Implemented several automated timing guards to expire sensitive data entry modes (like API key pasting) after a period of inactivity. * **Modern Event Migration**: Migrated several high-frequency chat listeners to the modern `AsyncPlayerChatEvent` for better performance and compatibility with 1.20+ servers. * **Memory Refresh Correction**: Fixed several logical errors in the `/ai refresh` command to ensure the correct context is preserved during conversation summaries. * **Null Safety Audit**: Hardened the entire pipeline to handle several edge cases where player objects or API responses might be null, preventing console spam. --- ## 🛠️ Summary for Server Owners NSR-AI v1.5 is a stability-focused release for the 1.x series. We trimmed unused features and optimized the core engine to keep NSR-AI fast and stable. **Upgrade Instructions**: Simply replace your old JAR with v1.5. Your `config.yml` and `knowledge.yml` will be preserved and optimized automatically. --- *Optimized for Speed. Hardened for Stability. Built for the Future.* **NSR-AI 1.5.** 🎮 ⚡ 🧠

# NSR-AI v1.4 — The Developer Empowerment Update > **Plugin Version:** 1.4 &nbsp;|&nbsp; **API Version:** 3.0-pre &nbsp;|&nbsp; NSR-AI v1.4 is the most significant update for developers and server owners to date. This release transforms NSR-AI from a standalone tool into a full-fledged **Development Platform** — featuring a completely rebuilt programmatic API, granular AI controls, a powerful chat interception layer, and deep stability hardening across every system in the codebase. Whether you're a server admin who wants plug-and-play reliability, or a developer building on top of NSR-AI, this update delivers. --- ## 📋 Quick Summary | Area | What's New | |---|---| | 🆕 **New Features** | Privacy system, Pet API, session control, command routing, middleware, and more | | 🐛 **Bug Fixes** | Several critical, security, pet, and engine stability fixes | | ⚡ **Optimization** | Major RAM reduction, CPU hardening, and full codebase consolidation | | 🛠️ **Developer API** | Builder-pattern registration, async futures, interceptors, RAG access | --- ## 🔗 Jump To Section [🆕 New Features](#-new-features) &nbsp;·&nbsp; [🐛 Bug Fixes & Stability](#-bug-fixes--stability) &nbsp;·&nbsp; [⚡ Performance & Optimization](#-performance--optimization) &nbsp;·&nbsp; [🛠️ Developer API](#-developer-api) --- ## 🆕 New Features ### ⚡ Asynchronous High Performance NSR-AI v1.4 completely decouples the AI engine from the Minecraft main thread, keeping your server running smoothly at all times. - **Zero-Lag AI Requests**: `askAI` and `sendMsg` now run entirely in the background — your server stays at 20 TPS even during complex AI reasoning. - **Async Persistence**: Saving AI logs via `SaveMsg` or updating the Knowledge Base no longer causes disk lag or server hiccups. - **Future-Ready API**: All critical paths now use `CompletableFuture`, giving developers precise control over when to handle AI responses without blocking the game thread. --- ### 🔌 Chat Interception System (Middleware) NSR-AI 1.4 introduces a powerful **Interceptor System** that allows addons to sit between the player and the AI, enabling custom processing at every stage of a conversation. #### Middleware Capabilities Addons can now register an `AIInterceptor` to: - **Read & Edit Player Input** — Modify what the player says before it reaches the AI. - **Read & Edit AI Response** — Transform the AI's answer (e.g. add branding or filter content) before the player sees it. - **Cancel Interactions** — Block specific inputs or responses based on custom logic (e.g. filtering bad words or enforcing game rules). #### Knowledge Base Bridge (RAG Access) - **Programmatic Access**: Addons can now query and mutate the `knowledge.yml` store directly. - **Hierarchical Permissions**: `read-knowledge` and `edit-knowledge` nodes control access globally and per-addon. - **Addon Identification**: The core plugin now uses stack-trace analysis to verify which addon is making an API call, preventing unauthorized knowledge tampering. #### Smart System Prompt Injection - **Core Context Extension**: Addons can use the `onSystemPrompt` interceptor to append dynamic instructions to the `/ai` global system prompt. - **API Isolation**: When an addon calls `askAI` or `sendMsg`, the core NSR-AI system prompt is **bypassed**, allowing the addon to supply its own pure system instructions. #### Universal Command Routing (`/aia`) - **Addon Namespace**: Commands are now routed via `/aia <AddonName>`, keeping `/ai` exclusively for core features. - **Tab Completion Delegation**: The core plugin handles the first argument (addon list) and then delegates all subsequent arguments and tab suggestions to the target addon. - **SimpleAddon Builder**: Enhanced to support `.onTabCompleteHandler()` for rapid development. #### Integrated Pet System API - **AIPet Data Model**: Addons can now programmatically access pet details (Name, Mood, Bond, Level, Hunger, etc.). - **Dynamic Manipulation**: New API methods allow addons to change a pet's mood, bond, or level on the fly — perfect for RPG or training addons. - **Status Interrogation**: Fetch a list of all pets owned by a player to display in custom GUIs or menus. --- ### 🛡️ Advanced Permission Architecture With great power comes great responsibility. NSR-AI 1.4 adds a multi-layered permission system to keep your server secure. - **Global Master Switch**: A central `permissions.yml` allows admins to disable chat reading or editing for **all** addons at once. - **Automatic Per-Addon Folders**: NSR-AI automatically creates a dedicated folder and `permissions.yml` for every registered addon. - **Granular Permissions**: Control exactly what each addon can do — `read-player-input`, `edit-ai-response`, `cancel-player-input`, and more. --- ### 🧠 Smart AI Routing The internal engine has been upgraded with intelligent routing logic that handles multi-provider setups seamlessly. - **Provider Sovereignty**: Automatically detects whether a key is Gemini, Claude, or OpenAI and formats the request perfectly for each provider. - **Dual-Mode Intelligence**: Automatically switches between Player API keys and Global Fallback keys based on developer requirements. - **Thread-Safe Memory**: Shared memory and conversation histories are now handled with full thread-safety, ensuring data integrity during async operations. --- ### 🔄 Advanced Session & Memory Control Developers now have granular control over how the AI remembers and forgets across conversations. - **Summarize Chats**: Compress long conversations into a summary that the AI retains in its memory. - **Cache Refresh / Clear**: Manually reload a conversation session from disk or wipe it entirely for a fresh "clean slate." - **Memory Access**: Programmatically read, update, or clear the AI's long-term summaries for each player. - **Shared Memory Store**: A global key-value store that allows different addons to share context with each other. --- ### 🛠️ Flexible Component Reloading You no longer have to reload the entire plugin for a small change. The new API supports targeted reloads for any component: | Mode | What It Reloads | |---|---| | `FULL` | Everything | | `CONFIG` | `config.yml` only | | `KNOWLEDGE` | RAG knowledge base only | | `FEATURES` | Feature toggles only | --- ### ⚡ Dynamic Model & Provider Control Take full control over the AI engine programmatically, without ever restarting the server. - **Global Swapping**: Change the server's default model or API provider (Gemini, OpenAI, Claude) on the fly via the API. - **Per-Request Overrides**: Addons can specify a different model or provider for a specific request without affecting global settings — perfect for complex tasks that require a "Pro" model. --- ### 🏗️ Structured Addon Command Aliases NSR-AI 1.4 overhauls how addons integrate commands into the server, providing a clean, collision-free namespace. - **Dedicated Namespace**: Addons use `/aia`, leaving `/ai` exclusively for core plugin features. - **Custom Aliases**: Every addon can define a short "Main Command" alias (e.g. `/aia aps`). - **Deep Tab Completion**: Addon aliases are automatically suggested, and sub-commands are fetched directly from the addon for a professional, native feel. - **Collision-Free Routing**: Commands are routed based on aliases, preventing multiple addons from conflicting with each other. --- ### 🛡️ Privacy & Anonymization (Opt-In / Opt-Out) NSR-AI 1.4 introduces a robust privacy layer that gives players full control over their data. - **Privacy Mode (Opt-In)**: Players can use `/ai opt in` to enable maximum privacy. This swaps sensitive information (like Player Names and IPs) with random codes (e.g. `PlayerName` → `R2d13n`) before sending data to the AI. It also **blocks all addon and plugin access** to the player's chat, preventing any middleware from reading or editing their AI interactions. - **Normal Mode (Opt-Out — Default)**: By default, NSR-AI uses real names and allows registered addons to process messages normally, ensuring maximum compatibility with AI extensions. - **New Command**: `/ai opt <in|out>` allows players to toggle between modes instantly. --- ### 📜 V1 Legacy Support & Clean-up To ensure a smooth transition from older versions, NSR-AI v1.4 retains **100% backward compatibility** for all core chat addons from v1.2 and v1.3 (`AIMessage` & `AIResponse` systems). --- ## 🐛 Bug Fixes & Stability NSR-AI 1.4 has been hardened with **several** critical stability and security fixes across all major systems. ### 🔴 Critical Fixes - **Addon Unload Loop**: Fixed a critical bug where only the **first** addon was unloaded during `/ai reload`. All other addons remained as ghost instances in memory, causing duplicates, memory leaks, and unpredictable behavior after every reload. - **API Key Selection Ignored Overload**: The key rotation system had broken logic that could return a rate-limited key back to the caller, causing `429 Too Many Requests` errors to cascade to players. Now properly consults the `OverloadedKeyManager` before selecting a key. - **API Key Leaked in Logs**: When a global API key was rate-limited, the **full raw key** was printed to the server console — a serious security vulnerability. Now only the last 4 characters are shown (e.g. `***a1b2`). - **Plugin/Addon Registration Bypass**: `registerPlugin()` and `registerAddon()` accepted any plugin or addon without checking the security ban list, allowing a banned addon to bypass restrictions by registering programmatically. Both methods now validate against `SecurityManager` before granting access. --- ### 🛡️ Privacy & Security - **Smart Anonymization**: Fixed a bug where names could be partially replaced (e.g. "Bob" inside "Bobby"). Now uses Regex word boundaries to ensure only exact name matches are anonymized. - **Robust De-anonymization**: Added case-insensitive matching for privacy codes to ensure AI responses are always correctly converted back to real player names. - **IP Protection**: Hardened IP detection logic to prevent data leaks to external AI providers. - **Plugin-Level Banning**: Added `validatePlugin()` to `SecurityManager` so entire Bukkit plugins (not just addons) can be banned. The API bridge is severed at runtime with a clear log warning, and the fix is fully backward compatible with older security JARs. --- ### 🐾 Pet System Robustness - **Fixed Immortal Pets**: Pets now correctly lose health when damaged. Fixed a logic error where health was reset to max every game tick. - **Dynamic Hunger & Health**: Pet status bars are no longer stuck at full. Hunger now decreases over time, and pets only regenerate health if well-fed (Hunger > 80). - **NPE Prevention**: Added safeguards for unsupported entity types and pets without nicknames, preventing console errors during pet interactions. --- ### ⚙️ Core Engine Stability - **Thread-Safe Memory**: Migrated conversation history to `CopyOnWriteArrayList` to prevent `ConcurrentModificationException` during asynchronous AI processing. - **Thinking Animation Safety**: Added null-checks to the thinking animation system to handle player disconnections gracefully. - **Task Management**: Optimized background tasks to prevent task accumulation during plugin reloads. - **ChatLogger Null Guard**: Fixed a `NullPointerException` crash when chat logging was disabled in config but players were actively chatting. - **Knowledge Base Save Fix**: Fixed a data corruption bug where the knowledge base could become unreadable after saving if any keyword contained dots or special YAML characters. Entries are now written individually with proper YAML path notation. - **Player Quit Cleanup**: Removed a duplicate `clearApiKeys()` call that was causing unnecessary overhead on player disconnect. --- ## ⚡ Performance & Optimization ### ⚡ API Infrastructure Stabilization (The GitHub Transition) Due to significant usage spikes observed recently, we have overhauled our update and security infrastructure to ensure 100% uptime and reliability. - **Cloudflare to GitHub Migration**: The update and security fetch engine has been migrated from dynamic Cloudflare Workers to a high-performance, static GitHub-hosted manifest architecture. - **Unified Fetch Logic**: The plugin now performs a single, consolidated fetch for all versioning, security, and bugfix data, drastically reducing network overhead and preventing request-related throttles. - **Local Filtration Engine**: Implemented client-side version matching for bug fixes. The plugin now downloads the global manifest and identifies relevant patches locally, removing server-side processing dependencies. ### Core Infrastructure Hardening - **Runtime Security Bridge**: Implemented `validatePlugin` and `validateAddon` in `SecurityManager`. Banned plugins are now disconnected at registration time, preventing unauthorized API access. - **Thread Safety Overhaul**: Converted all critical plugin maps (admin status, cooldowns, shared memory) to `ConcurrentHashMap` to prevent `ConcurrentModificationException` during async API operations. - **API Reliability**: Fixed "dummy" retry logic — the plugin now properly attempts 3 retries with exponential backoff for failed AI requests. - **Personal API Key Privacy**: Added hooks to `PlayerListener` to respect privacy settings — players who opt out of privacy will no longer have their chat logged by the global `ChatLogger`. - **Manager Stability**: - **PlayerDataManager**: Fixed unsafe inventory casting and added default value safety for all player stats. - **ApiKeyManager**: Fixed Claude/OpenAI validation endpoints (now uses POST for Claude and `/v1/models` for OpenAI). - **ConversationManager**: Fully converted to `CopyOnWriteArrayList` for consistent thread-safe history management. - **Shutdown Persistence**: Added explicit save calls in `onDisable` for Knowledge Base and Saved Chats to ensure zero data loss during server restarts. --- ### Utility & Performance Optimization - **Massive Masking Optimization**: Refactored `ChatLogger` key masking to eliminate an O(N×M) bottleneck. The logger no longer scans every player's key for every message — it now targets only relevant keys, drastically reducing CPU usage on large servers. - **Utility Thread Safety**: - **ConfirmationManager**: Migrated to `ConcurrentHashMap` for fail-safe async cleanup. - **AdminRecipientManager**: Implemented `CopyOnWriteArrayList` to prevent broadcast crashes. - **Logic Hardening**: - **StringUtil**: Fixed Levenshtein matching to prevent false-positive "best matches" when input confidence is low. - **UpdateChecker**: Hardened version parsing to support complex version strings (e.g. `-pre`, `-alpha`) without numeric parsing errors. - **Data Integrity**: Added UUID parsing guards in `AdminRecipientManager` to handle manual configuration errors gracefully. --- ### Pet System Hardening (Final Stability Pass) - **Performance Overhaul**: Refactored `PetListener` chat processing to only scan relevant pets, eliminating O(N) server-wide scans and preventing chat-induced TPS drops. Implemented Regex Pattern caching on the `Pet` object itself to prevent thousands of expensive regex recompilations during chat events. - **RAM Optimization (Lazy Loading)**: Rewrote `PetDataStorage` and `Pet` inventory handling. The server no longer creates empty Bukkit `Inventory` objects in memory for every loaded pet — inventories are now fully lazy-loaded on demand, saving significant heap memory on servers with large numbers of pets. - **Thread-Safe Concurrency**: Converted all internal mapping structures inside `PetManager` to `ConcurrentHashMap` (replacing unsafe `HashMap` instances) and implemented `ThreadLocal` date formatting in `PetDataStorage`. This entirely eliminates the risk of `ConcurrentModificationException` during async pet chat processing. - **Feature Completion**: Fully implemented missing subcommands in `/ai pet` (share, link-redeem, unlink), bridging the gap between command usage and backend logic. - **Logging Precision**: Upgraded pet chat logs to millisecond precision to prevent message overwrites during rapid-fire AI conversations. --- ### Manager Architecture Hardening (Final Platform Audit) - **Universal Thread-Safety**: All internal managers (Knowledge, Privacy, Settings, Shop, Addon, Data, ActiveConversation, SaveChat) have been fully migrated to `ConcurrentHashMap` and thread-safe data structures. This eliminates the risk of `ConcurrentModificationException` during high-frequency AI interactions. - **Atomic File Persistence**: Implemented `synchronized` file locks for all YML and Binary storage managers. This prevents data corruption during simultaneous async AI responses and ensures player settings, API usage counts, and chat histories are always saved correctly. - **High-Performance Caching**: - **PermissionManager**: Now features a memory-based permission cache, eliminating redundant disk I/O on every permission check — removing a primary source of server stutters. - **PlayerDataManager**: Implemented a memory cache for player stats, ensuring the AI can access player context instantly without disk reads. - **Addon Management System Hardening**: - **Memory-Direct Loading**: Refactored `AddonManager` to eliminate expensive temporary file creation/deletion when scanning addon JARs. Metadata is now read directly from the JAR stream via `InputStreamReader`, removing a major source of disk I/O lag and preventing file-lock errors. - **API Modernization**: Marked the legacy `Addon` interface as `@Deprecated` to streamline the v1.5 transition while maintaining full v1.4 backward compatibility. - **Memory Leak Prevention**: Implemented try-with-resources for all Addon JAR loading, ensuring `URLClassLoader` and `JarFile` handles are closed properly. - **Config & Resource Integrity**: - **Resource Leak Fix**: Hardened `ConfigUpdater` with try-with-resources for default configuration streams, preventing stranded file descriptors during repeated plugin reloads. - **UTF-8 Enforcement**: Standardized on `StandardCharsets.UTF_8` for all configuration and addon metadata reading, ensuring consistency across different server locales. - **Non-Destructive Updates**: Hardened `ConfigUpdater` to be additive-only, safely preserving custom user keys and data across version upgrades. --- ### Extreme Optimization & RAM Efficiency (The Performance Overhaul) - **Massive Codebase Consolidation**: - Refactored fragmented AI calling logic into a **unified core pipeline**. - Deleted nearly **500 lines of redundant code** across 12+ legacy provider methods (Summarization, Grammar, Headings, Extraction). - **Legacy Data Package Archiving**: Safely commented out the entire `com.nsr.ai.plugin.data` package (14 legacy DAO classes). This unused skeleton code is now archived, preventing accidental compilation, reducing the final JAR size, and shrinking the overall codebase footprint. - The plugin is now significantly smaller, faster to load, and easier to maintain. - **Critical RAM Reduction**: - **Inventory Stripping**: Removed `ItemStack` inventory caching from the `PlayerData` object. Data is now fetched directly from the online player only when needed, reducing heap memory usage by **up to 90%** on high-player-count servers. - **Conversation TTL (Time To Live)**: Implemented an automated background task that purges inactive conversation histories from memory after 30 minutes of inactivity. - **CPU & Lag Prevention**: - **Direct Search Algorithm**: Optimized `KnowledgeManager` search logic to perform direct iteration, eliminating expensive `HashMap` copying on every query. - **Resource Singletons**: Standardized `Gson` and `OkHttpClient` as shared, high-performance singletons across all managers. - **Event Handler Cleanup**: Removed empty event listeners (e.g. `onPlayerMove`) to ensure the plugin has **zero** idle CPU overhead for non-AI tasks. - **Persistence Hardening**: Optimized `PlayerDataManager` and `ConversationManager` to ensure all data is persisted with atomic safety during async operations. - **Cryptographic & Utility Speedups**: - **Encryption Cache**: Implemented a `ConcurrentHashMap` cache for PBKDF2 key derivation in `EncryptionUtil` and `SecurityUtil`, eliminating massive CPU spikes during data decryption and player-specific key generation. - **ThreadLocal Caching**: Refactored `ChatLogger` to use `ThreadLocal<SimpleDateFormat>`, preventing thousands of unneeded object allocations per minute during heavy logging. - **StringBuilder Refactor**: Replaced inefficient string concatenation in `MessageFormatter` with `StringBuilder`, significantly reducing memory fragmentation and garbage collection pauses. - **Randomness & String Optimization**: Consolidated `SecureRandom` and `ThreadLocalRandom` usage for faster generation. Lifted invariant string transformations out of loops in `StringUtil` and pre-compiled Regex patterns in `UpdateChecker` for tighter execution. - **Targeted Manager Optimizations**: - **ActiveConversation CPU/Memory**: Completely removed the `animationFrame` tracking map from `ActiveConversationManager`. By utilizing localized closure state within the `BukkitRunnable`, thousands of auto-boxing memory allocations and map mutation operations that previously occurred every second during active AI conversations are now eliminated. - **BugFixManager Memory**: Removed private `OkHttpClient` and `Gson` instantiations, routing requests through the plugin's global singletons to eliminate duplicate thread pools. - **ShopManager CPU**: Extracted and pre-compiled the shop query Regex Pattern (`SHOP_QUERY_PATTERN`), stripping a heavy `Pattern.compile()` call out of the high-frequency chat event path. - **AddonInfo Safety**: Marked all fields as `final`, guaranteeing immutability and enabling JVM memory access optimizations for addon metadata DTOs. --- ## 🛠️ Developer API > **API Version:** 3.0-pre &nbsp;|&nbsp; Fully backward compatible with v1.2 and v1.3 addons. NSR-AI 3.0-pre replaces the old, complex registration system with a modern, **builder-pattern API** that makes integration effortless. All critical paths are async-first, giving developers full control without blocking the game thread. ### 1. Simple Addon & Plugin Registration Register your extension with a single line of code. NSR-AI handles all the complex reflection and internal logic automatically. ```java // Register a native NSR-AI addon NSRAI.getAPI().registerAddon(myAddon); // Register an existing Bukkit plugin that wants AI features NSRAI.getAPI().registerPlugin(myPlugin, myAddon); ``` - **`registerAddon(AIAddon)`** — For native NSR-AI extensions. - **`registerPlugin(Plugin, AIAddon)`** — For existing Bukkit plugins that want to add AI features. --- ### 2. Flexible AI Parameters (Temperature, Top-P, Top-K) You no longer have to settle for the default AI "brain." Developers can programmatically adjust how the AI thinks for each specific request: - **Temperature** — Control creativity vs. factual precision. - **Top-P & Top-K** — Fine-tune the probability distribution of the AI's word selection. - **Max Tokens** — Set strict limits on response length to control costs. - **Custom Settings** — Inject ANY provider-specific parameter (e.g. OpenAI's `presence_penalty`) directly into the JSON request body. --- ### 3. Async CompletableFuture API All API calls are fully non-blocking. Use standard Java `CompletableFuture` chains to handle responses cleanly. ```java api.askAI(player, "What is the weather today?") .thenAccept(response -> player.sendMessage(response)) .exceptionally(err -> { err.printStackTrace(); return null; }); ``` --- ### 4. Knowledge Base (RAG) Access ```java // Read from the knowledge base String info = api.getKnowledge("server-rules"); // Write to the knowledge base api.setKnowledge("server-rules", "No griefing allowed."); ``` Requires the `read-knowledge` / `edit-knowledge` permissions to be granted to your addon in its `permissions.yml`. --- ### 5. Session & Memory Management ```java // Summarize a player's conversation history api.summarizeChat(player); // Clear a player's conversation session api.clearSession(player); // Access shared memory between addons api.getSharedMemory().put("my-key", "my-value"); ``` --- ### 6. Interceptor Registration ```java api.registerInterceptor(new AIInterceptor() { @Override public String onPlayerInput(Player player, String input) { return input.replace("badword", "***"); // Edit input before it hits the AI } @Override public String onAIResponse(Player player, String response) { return "[MyAddon] " + response; // Add branding to responses } }); ``` --- ### 7. Dynamic Model & Provider Override ```java // Override the model for a single request AIRequest request = new AIRequest(player, "Summarize this:") .withModel("gemini-1.5-pro") .withProvider(AIProvider.GEMINI); api.askAI(request).thenAccept(player::sendMessage); ``` --- *Developer-First. Admin-Controlled. Hardened Security. Effortless Integration.* **NSR-AI 1.4 — The Platform for Intelligence.** 🎮 ⚡ 🧠

# NSR-AI 1.3: The Hybrid Intelligence Engine – Technical Briefing Welcome to the next evolution of server-side intelligence. **NSR-AI v1.3** is a high-performance middleware architecture designed to bridge the gap between advanced Large Language Models (LLMs) and the Minecraft environment. This update is not just a feature drop; it is a fundamental shift toward precision control, latency masking, and adaptive memory engineering. --- ## 🛠️ The Interactive Control Pipeline We have re-engineered the communication layer to give you granular control over the AI's generation stream. ### 1. Granular Generation Controls - **🛑 [Stop] — Interrupt Display Stream**: Immediately "mutes" the AI's current message. Perfect for when you need to pivot your query or handle a sudden in-game threat. * **Technical Detail:** Note that clicking `[Stop]` interrupts the *display stream* only. Because the request has already been sent to the API provider, **tokens are still consumed.** Think of it like canceling a broadcast; the signal was already sent, you just stopped listening. - **✍️ [Edit] — Prompt Refinement**: Mistyped a command? The `[Edit]` button acts as a "Time Machine." It instantly pulls your last message back into your chat bar so you can fix typos or tweak your instructions without retyping the whole paragraph. - **🔄 [Regenerate] — Multi-Mode Divergence**: If the AI didn't quite get it right, don't retype. Just hit `[Regenerate]` and choose a new "Brain Mode": `Detailed`, `Simple`, `Default`, `Creative`, or `Concise`. The AI will try again with a different perspective. ### 2. Fact-Checking & Knowledge (RAG) Say goodbye to AI "hallucinations" (when AI makes things up). - **The "Cheat Sheet" System:** Using **Retrieval Augmented Generation (RAG)**, the AI reads your `knowledge.yml` file before it speaks. It extracts facts about your server lore, rules, or shop prices and uses them as a "cheat sheet" to give 100% accurate answers. --- ## 🏛️ Advanced Conversation Chronicles: `/ai chat` Your interactions are more than just text—they are serialized data structures that define your server's lore. - **Persistent State Management**: Use `/ai chat save <name>` to immortalize complex role-play narratives. This saves the **AI's current memory state**, not just the text. - **The Checkpoint System**: Like a save-game in an RPG, the **Checkpoint System** (`/ai chat resume`) lets you jump back to a previous part of the conversation. If a narrative goes wrong, you can "rewind" to a specific checkpoint and try a different path. --- ## 🧠 Adaptive Context & Memory Distillation We have moved beyond primitive history limits. The AI now manages its own "attention span" to stay sharp. - **Context Meter (The HUD)**: You can see exactly how much the AI remembers via a percentage meter (e.g., `Context: 24%`). - **Memory Distillation (Auto-Summary)**: As the chat gets too long, the AI doesn't just forget; it "writes a summary" of the past. It turns 50 messages of history into 1 concise "Diary Entry." This keeps the AI smart for thousands of messages without causing lag. - **The Efficiency Edge (Tokens, Time & Cost):** - **Token & Cost Optimization:** By distilling thousands of words into compact summaries, we drastically reduce the "payload" sent to the API. You only pay for the essential context, not redundant history, significantly cutting your API costs. - **Ultra-Fast Processing:** Smaller, distilled contexts are processed much faster by AI providers. This reduces the "Thinking" time, delivering answers to your chat in record time. - **Peak Accuracy:** Distillation removes the "noise" of old, irrelevant chat data. This prevents the AI from getting confused by outdated topics, ensuring every answer is sharp, factual, and hyper-relevant to the current conversation. - **Multi-API Sovereignty**: You are never locked into one brain. Switch between **Gemini**, **Claude**, and **OpenAI** in real-time. If one key hits a limit, the system can automatically cycle to a fallback key for zero downtime. --- ## 🔌 The Unified Add-on Portal: `/aia` NSR-AI 1.3 functions as a **Micro-Kernel platform**. The core handles the intelligence, while the extensions handle the gameplay mechanics. - **Standardized Extension API**: The `/aia` command portal is your "Control Center." Manage all modular add-ons like `AFK Trackers`, `Player Stats`, or `Economy Bridges` from one place. - **Ecosystem Integrity**: Check versions, verify authors, and manage technical health through a single, clean command structure. --- **Powering your world with intelligence that is Complex Inside, Simple Outside.** *Unmatched Power. Zero-Lag Performance. Hardened Security. Effortless Control.* **NSR-AI 1.3: Elevate Your Protocol.** 🎮⚡🧠

NSR-AI v1.2.1 Patch Update ⚙️ Critical Hotfix for AI Response & Message Sender Module A new maintenance release is rolling out: NSR-AI 1.2.1. This patch delivers major stability improvements by fixing two core issues inside the nsr-ai-api layer: 🔧 Fixed Issues 1. AI Response Handler Bug Some users on v1.2 experienced delayed or incomplete AI replies. This has been fully resolved with optimized pipeline handling. 2. AI Message Sender Error Outgoing AI messages were failing under certain player data states. This patch stabilizes the message dispatch flow for all players. 🔄 Auto-Update Policy (Important) Players currently on NSR-AI v1.2 will receive an automatic bug-fix update to v1.2.1. This is a targeted patch. Auto-update applies ONLY to v1.2 users. Earlier versions remain unaffected, as the bug existed exclusively in the 1.2 build. 🛡️ Stability Boost. Cleaner Logs. Smoother AI. NSR-AI 1.2.1 ensures a more reliable in-game AI experience, sharper message delivery, and fewer interruptions. Your server AI just leveled up. 💬 Powering your world with smarter gameplay.

# NSR-AI v1.2: Enhanced Pet System, API Key Management & Open-Source Addon Platform Welcome to a smarter, more resilient NSR-AI! This update introduces a highly advanced API Key Management system, designed for ultimate control, security, and flexibility, alongside the groundbreaking **NSR-AI Open-Source Addon API** and significant enhancements to the Pet System. ## ✨ Core Improvements The entire API key, pet, API, and configuration systems have been thoroughly modified to enhance security, efficiency, and speed. * **Unmatched Security:** Stored keys are protected with military-grade AES-256-GCM encryption, salted with your unique player data. * **Player Empowerment:** You have full control over your own keys directly in-game, reducing reliance on server admins. * **Enhanced Reliability:** The intelligent rotation and fallback system ensures a much smoother and more reliable AI chat experience. * **Simplified Error Messages:** All API key errors now use a clear three-part format: `Error [Code]: [Name]. Suggestion: [Fix]`. Player-specific errors are shown only in-game, keeping the console clean. * **Enhanced Help Command:** The `/ai help` command now provides detailed descriptions for all commands and subcommands, making it easier for users to understand plugin functionalities. ## 🚀 New Features & Major Enhancements ### 🔑 Advanced API Key Manager The entire key system has been rebuilt from the ground up, now consolidated under the powerful `/ai apikey` command. #### Refined API Key Entry Workflow When you type `/ai apikey`, you will now see these instructions: * **To add a session-based key (temporary):** Directly paste your API key in chat. * **To store an existing session-based key (permanent):** Type `/ai apikey store <projectId>`. This command will convert your most recently added session key into a permanent stored key, associating it with the provided `<projectId>`. * **To store a new API key from scratch (permanent):** First type `/ai apikey`, then type `store-<your_api_key>`. The system will automatically generate a unique Project ID for it. #### Intelligent Key Rotation & Fallback NSR-AI now automatically rotates through your available API keys for each request. This distributes the load and maximizes uptime. * **Automatic Fallback:** If a key is busy, rate-limited, or hits an error, the system automatically tries the next available key in your list, ensuring your conversation continues seamlessly. #### Detailed Key Status & Statistics Use `/ai apikey info <key-id>` to see a detailed breakdown of your key's performance. * **Key Status Glossary:** * **🟢 Active (`ACTIVE`):** The key is valid and ready, waiting in the wings. * **🟠 Using (`USING`):** This is the key currently processing your AI requests. * **🟡 Overloaded (`OVERLOADED`):** The key is temporarily rate-limited. The system will automatically skip it and try again later. * **🚫 Limit Reached (`LIMIT_REACHED`):** The key has hit a hard usage limit (e.g., daily/monthly quota) and will be skipped until the quota resets. * **🔴 Inactive (`INACTIVE`):** The key is invalid or has an error (e.g., wrong model, or other error ). It will not be used until it is changed to the active through timer reset. * **Statistics Glossary:** * **Uses:** The total number of successful AI responses this key has delivered. * **Errors:** How many times the key has failed (e.g., other API errors). * **Fallbacks:** The number of times the key had to switch *from* this key to another one because of an error and also includes the due to rate limits. #### Manual Overload Timer Removal A new command has been added to manually clear the overloaded status of an API key. * **Command:** `/ai apikey timer <key-id> remove` * **Functionality:** This command allows administrators to immediately remove the rate-limited or overloaded status from a specific API key (either player-specific or global). This is useful if an API provider issue has been resolved, and you wish to re-enable the key before its natural cooldown period expires. * **Permissions:** This command requires player permissions. #### API Key Deletion A new command allows for the removal of unwanted or corrupted API keys. * **Command:** `/ai apikey clear <all|projectId>` * **Functionality:** This command enables you to delete specific API keys by their `projectId` or clear all your API keys. This is particularly useful for removing corrupted, expired, or unused keys, helping to maintain a clean and efficient API key management system. * **Permissions:** Requires players permissions to manage API keys. #### Automatic Provider Detection When you add a key, NSR-AI instantly detects the provider (Google, Anthropic, OpenAI) and assigns a suitable default model, streamlining the setup process. #### Per-Player Fallback System - You can now control whether the plugin uses server keys if your personal key fails. - **Command**: `/ai apikey fallback global <true|false>` - **Default**: `false`. The plugin will stop if your key fails. - **Tab Completion**: This new command has full tab-completion for ease of use. ### 📝 Enhanced Chat and Logging #### Chat History Saving Preference Players now have granular control over whether their AI chat conversations are saved to the plugin's logs. * **Command:** `/ai apikey msg save <true|false>` * **Functionality:** This command allows a player to enable or disable the saving of their AI chat history for their *active* API key. * If set to `true`, chat messages (excluding API key entry messages) will be logged. * If set to `false`, chat messages will *not* be logged. * **Default:** `false` (chat history saving is disabled by default for enhanced privacy). #### Enhanced Chat Logging and Session Management The plugin now features a robust chat logging system designed for clarity, organization, and session tracking. * **Dedicated Log Folders:** Player and admin chat histories are stored in separate, dedicated folders (`playerchathistory` and `adminchathistory`) within the plugin's data directory. * **Daily Log Rotation:** A new log file is automatically created for each day, ensuring logs are easy to navigate and manage. Files are named `chat-MM-dd-yyyy.log`. * **Intelligent Session Tracking:** * If a player disconnects and reconnects within 5 minutes, their chat continues to be logged in the same daily log file. * If a player reconnects after more than 5 minutes, or on a new day, a new session-specific log file is created. These files are appended with a numerical suffix (e.g., `chat-MM-dd-yyyy-1.log`, `chat-MM-dd-yyyy-2.log`), providing clear separation of chat sessions. * **In-Game Color Preservation:** Chat logs accurately preserve the in-game color formatting, making them easier to read and review. * **API Key Exclusion:** All API keys (global and player-specific) and direct API key entry messages (`store-<your_api_key>`) are strictly excluded from all chat logs to ensure maximum security and prevent sensitive information leakage. * **Pet Chat Logging (Optional):** Chat interactions with pets can also be logged in a dedicated `pet` folder under the player's name (if enabled). ### 🛡️ Security and Error Handling #### Enhanced Security While API keys are entered via chat, the plugin now employs advanced filtering to ensure that messages containing API keys (both global and player-specific) or those used for direct API key storage (`store-<your_api_key>`) are *never* written to the plugin's chat history logs. This provides an additional layer of security, preventing sensitive information from being inadvertently recorded. #### Error Message Philosophy - **For Player Keys:** Error messages for a player's personal key are **inbuilt** (hardcoded) and are **only shown to the player in-game**. The console remains clean. This is for security and privacy, as server owners do not have control over messages related to a player's personal API key. - **For Global Keys:** When a server-wide global key fails, a detailed, **inbuilt** error message is logged to the **console** for administrators. This log includes the API key type, error code, error name, and a suggestion for resolution. - **In-game Message:** If all available API keys (player-specific and global) fail to provide a response, a customizable `globalKeyFailMessage` (defined in `features.yml`) is displayed to the player in-game. ### 💻 User Interface #### Sleek Cyber-Console UI All `apikey` commands feature a clean, professional "cyber-console" theme, making the interface intuitive and stylish. #### Help Command Disclaimer A small disclaimer has been added to the `/ai help` command, informing users that some commands might be misconfigured or have incorrect descriptions based on server settings. ### 🔒 Configuration Encryption & Security - **Automatic Configuration Encryption:** Sensitive data in `config.yml`, including the `admin-activation-code` and global API keys, are now automatically encrypted. The plugin intelligently encrypts new plain-text values on reload, so you can safely add or change keys in the config file. - **New Admin Code Command:** Server operators can now use the `/ai admincode` command to safely view the current admin activation code. This code is now generated automatically if it's not set in the config. ### 🐞 Bug Fixes and Stability Improvements This update addresses several critical issues to enhance the plugin's reliability and security: * **Configuration Reload System Fixed:** Resolved an issue where configuration changes (for `config.yml`, `features.yml`, etc.) were not being applied correctly after a `/ai reload` command, despite the plugin reporting a successful reload. The reload system now accurately updates all relevant settings. * **API Key Logging Prevention:** Fixed a security vulnerability where API keys, when entered via chat, could inadvertently be saved in chat history logs. The plugin now strictly prevents any API key information from being written to logs, ensuring sensitive data remains secure. ### 📂 File Organization - Data files have been reorganized into new folders for better management: - `bug.txt` is now at: `plugins/NSR-AI/security/bug.txt` - `bugfix.reloading` is now at: `plugins/NSR-AI/security/bugfix.reloading` - `reserved-nicknames.yml` is now at: `plugins/NSR-AI/pets/reserved-nicknames.yml` - `death_log.yml` is now at: `plugins/NSR-AI/pets/death_log.yml` This update empowers you with a robust and transparent key management system. We can't wait for you to experience the new level of control and reliability! # 🛡️ Advanced Security Architecture NSR-AI is built with a security-first mindset. The plugin employs a multi-layered strategy to protect sensitive data, particularly player API keys. This section details the core components of our security framework. ### Core Security Files These files are the foundation of the plugin's encryption system and are located in the `plugins/NSR-AI/security/` directory. * **`master_secret.conf`**: This file contains a unique, randomly generated secret value. It acts as the primary seed for generating the server's main encryption key. **Never share this file.** * **`server.salt`**: This is a random value used to add complexity to the encryption process, making it more resistant to pre-computation attacks (like rainbow tables). It ensures that even if two servers had the same master secret, their final encryption keys would be different. * **`master.key`**: This is the final, derived **Server Master Key**. It is generated by combining the `master_secret.conf` and the `server.salt`. This is the key that performs the second layer of encryption on all stored API keys. ### Player API Key Storage Security When a player stores an API key using `/ai apikey store` or the `store-<key>` format, it is never saved in plain text. Instead, it undergoes a robust, three-layer encryption process. 1. **Storage Location**: Stored keys are saved in the `plugins/NSR-AI/player_keys/<player_uuid>/` directory. Each player has their own dedicated folder, named after their unique player ID (UUID). Within this folder, individual API keys are stored in separate `.yml` files, named after their Project ID (`<project_id>.yml`). This player-specific folder also contains the player's unique `master.key` and `salt.bin` files, which are crucial for deriving their Player Master Key. 2. **Layer 1: Key-Specific Encryption**: * First, a unique encryption key (`userKey`) is derived from a combination of the **player's UUID** and the **key's Project ID**. * The raw API key is then encrypted with this `userKey`. This means every single stored key has its own unique first layer of protection. 3. **Layer 2: Player-Specific Master Key Encryption**: * The already-encrypted data from Layer 1 is then encrypted *again*, this time using the **Player Master Key**. Each player has their own unique Player Master Key, derived from their `master.key` and `salt.bin` files, adding a crucial layer of individual security. 4. **Layer 3: Server-Wide Master Key Encryption**: * The already-encrypted data from Layer 2 is then encrypted *again*, this time using the **Server Master Key** (`master.key`). * This triply-encrypted key is what is actually written to the player's `.yml` file. 4. **Integrity Verification (Hashing)**: * Alongside the encrypted key, the plugin stores a **SHA-256 hash** of the final encrypted data. * When the server starts and loads the key, it re-calculates the hash. If the new hash does not match the stored hash, the data has been tampered with and will not load the key, logging a security warning. This multi-layered approach ensures that API keys are exceptionally secure. An attacker would need to compromise the server to get the `master.key`, `server.salt`, `master_secret.conf`, *and* know the specific player's UUID and Project ID to even begin to decrypt a single key. # 🤝 Introducing the NSR-AI Open-Source Addon API We are thrilled to announce the open-sourcing of the **NSR-AI Addon API**! This new API layer transforms NSR-AI into a powerful platform, allowing developers to create rich, integrated addons without directly modifying the core plugin. It provides a secure and stable bond, enabling addons to interact with key functionalities, much like a dedicated communication channel. ### ✨ Key Addon Capabilities: * **Admin Mode Management**: Addons can now programmatically toggle and monitor a player's NSR-AI admin mode, enabling advanced moderation or event-driven features. * **Advanced GUI Customization**: Developers can register and open their own custom Graphical User Interfaces, offering full control over layout and interaction within the NSR-AI ecosystem. * **Player AI States**: Access and manage player-specific AI interaction settings, including AI chat cooldown status, remaining time, and AI enablement, allowing for smarter, context-aware addon behavior. * **Knowledge Base Interaction**: Addons can directly add, remove, and retrieve entries from NSR-AI's core knowledge base, enabling dynamic expansion or curation of the AI's understanding. * **Conversation History Control**: Gain programmatic control over player conversation histories, including clearing, summarizing, refreshing, and retrieving past interactions for analysis or custom display. * **Configuration Reloading**: Addons can trigger reloads of NSR-AI's main configuration, feature settings, and the knowledge base, allowing for dynamic updates without a server restart. ### 🛡️ Important Restrictions: To maintain NSR-AI's security, stability, and integrity, certain functionalities remain exclusively within the core plugin and are **not** exposed via the Addon API: * **No Security Bypass**: The API offers no methods to circumvent or disable NSR-AI's robust security mechanisms, including addon banning. * **No Bug Fixation Interference**: Addons cannot interfere with or disable the core plugin's critical bug fixation logic. * **No Direct API Key Management**: Addons cannot add new API providers or modify API key limits. Furthermore, addons **cannot steal player API keys** nor do they have direct control over them. The core plugin maintains absolute control over API key management, ensuring secure and efficient operation. ## 🐾 Pet System Enhancements This update brings significant new features and improvements to the pet system, making your companions more interactive and personalized. ### New Pet Types Introduced * **Expanded Pet Roster:** The plugin now supports a wider variety of Minecraft entities as pets, including: * Wolf, Cat, Horse, Parrot, Pig, Panda, Sheep, Cow. * **Technoblade Tribute Pig:** The Pig pet now features a special death message: "(pet name) never dies! 👑". ### Pet Features & Management * **Pet Inventory:** Pets now have their own inventories, accessible via `/ai pet inv`. * **Pet Details:** Use `/ai pet` to view details about your active pet. * **Pet Stats:** Pets now track `level`, `xp`, `health`, `hunger`, and `mood`. * **Stat Regeneration:** Pets periodically regenerate health and hunger, and their mood updates over time. * **Hunger and Health Decay:** Pets now experience natural hunger and health decay over time, requiring players to feed and care for them to maintain their well-being. * **Mood System Refinement:** Pet moods are now managed by an enum (HAPPY, NEUTRAL, SAD, HUNGRY, TIRED, ANGRY, FURIOUS) for more expressive behavior. ### 🔗 Shareable Pet Link System A groundbreaking feature allowing players to share access to their pets with friends, fostering a more social and interactive pet experience. * **Conditional Access:** Generate links that either grant immediate access or require owner approval. * **Custom Relationships:** Define unique relationships (e.g., "brother", "sister", "ally") for friends, influencing future pet interactions. * **Link Generation (`/ai pet share`):** * `/ai pet share <pet_name>`: Generates a link requiring owner acceptance. * `/ai pet share <pet_name> allow`: Generates a link for immediate access. * `/ai pet share <pet_name> <relationship>`: Generates a link with a custom relationship, requiring owner acceptance. * `/ai pet share <pet_name> <relationship> allow`: Generates a link with a custom relationship, immediate access. * **Link Usage (`/ai pet <link_code>`):** Players use this to activate links, triggering access or acceptance requests. * **Owner Acceptance:** Clickable chat messages for owners to accept or deny friend requests. * **Friend Management (`/ai pet removefriend`, `/ai pet relation`):** * `/ai pet removefriend <player_name> <pet_name>`: Owner removes a friend's access. * `/ai pet relation <pet_name> <player_name> <new_relationship>`: Owner changes a friend's relationship. * **Listing Commands:** * `/ai pet link list`: Shows *your own pets* that are linked with other players. * `/ai pet linked list`: Shows *other players' pets* that are linked with *you*. * **Player Unlinking (`/ai pet unlink <pet_name>`):** Friends can voluntarily remove their own access to a pet. * **Dynamic Relationships:** The system supports any custom relationship string typed by the owner, with "friend" as the default. * **Tab Completion:** Comprehensive tab completion for all new commands. * **Pet Inventory Access for Friends:** Added `/ai pet inv allow|disallow <pet_name> <player_name>` command to allow or disallow specific players to access a pet's inventory. * **Pet Barking:** Pets will now "bark" or make a species-appropriate sound when a non-owner/non-friend talks to them. ### Advanced Knowledge Search (Hybrid AI System) The `/ai data` command has been completely re-engineered into a sophisticated, hybrid AI system that seamlessly blends conversational AI with a precise, local knowledge base search. This new approach provides more accurate, context-aware answers while significantly optimizing API usage. This system operates on a multi-step principle known as **Retrieval Augmented Generation (RAG)**: 1. **Intent Recognition & Retrieval:** When you ask a question like `/ai data hey who is the owner of this plugin?`, the system doesn't just send your message to the AI. First, it intelligently analyzes your message to identify the core question ("who is the owner of this plugin?"). It then uses this core question to perform a highly targeted search within the `knowledge.yml` file, retrieving only the most relevant pieces of information. 2. **Augmented Generation:** Next, the system constructs a new, highly-detailed prompt for the main AI. This prompt includes your original, full message along with the specific, relevant information retrieved from the knowledge base. This acts as a "cheat sheet" for the AI, giving it the exact facts it needs to answer your question correctly. 3. **Natural, Contextual Response:** Finally, the AI processes this combined information and generates a single, natural-sounding response that incorporates both the conversational elements of your original message and the factual data from the knowledge base. The result is a fluid answer like, "Hello! The owner of the NSR-AI plugin is BlackForge." This advanced process ensures that you get the most accurate and relevant answers, drawn directly from the server's custom knowledge, while preventing the high costs and potential inaccuracies of sending large, irrelevant amounts of data to the AI.

# NSR-AI v1.2-pre - Pet Emotional Communication System! Get ready to connect with your beloved Minecraft pets like never before! Version 1.2 of NSR-AI introduces the **Pet Emotional Communication System**, a revolutionary feature that brings your tamed companions to life with unique personalities, moods, and the ability to chat with you. --- ## 🐾 Pet System ### Pet Linking & Nicknames * **Link Your Pets:** Use the `/ai pet tame` command while looking at a tamed and named pet to link it to the AI. This will allow your pet to start communicating with you. * **Unique Nicknames:** Give your pets a special nickname with `/ai pet nickname <nickname>`. Each pet's nickname must be unique! ### Advanced AI-Powered Chat * **Real Conversations:** Your pets now have their own AI-powered brain! They will respond to your messages with unique and in-character dialogue. * **Emotional Intelligence:** A pet's mood and its bond with you will directly affect its personality. A happy pet with a strong bond will be affectionate and playful, while a neglected pet might be cold and distant. * **Species-Specific Identity:** Every pet type has its own unique sound and set of emojis! Wolves will "woof," cats will "meow," and their messages will be full of personality. * **Check Your Pet's Mood:** Ask your pet "what is your mood" or "how are you feeling" to get a direct response about its current mood. ### New Commands * **`/ai pet list`:** See a list of all your linked pets and their status. * **`/ai pet info <pet_name>`:** Get detailed information about a specific pet, including its mood, bond level, and more. ### Pet Lifecycle * **Tamed & Linked Dates:** Your pet now remembers when it was tamed and when it was linked to the AI. Ask them about it! * **A Pet's Farewell:** When a pet is low on health, it will say a heartfelt goodbye. When a pet dies, its link with the AI is broken. If you try to talk to a pet that has passed away, it will respond with a special message. ### Ownership * **A Special Bond:** Only a pet's true owner can chat with it and change its nickname. Any other player who tries to interact with your pet will be ignored or receive a cold shoulder. --- ## 🔑 Per-Player API Keys * **Bring Your Own Key:** Players can now add their own API keys for Gemini, OpenAI, or Claude using the `/ai apikey ` command. * **Session-Based:** Player-provided API keys are only valid for the current session and are never stored on the server. * **Secure:** API keys are not visible to admins or in the console. * **Fallback System:** If a player has not provided their own API key, the server's global API key will be used as a fallback. ### New Commands * **`/ai apikey`:** then type the key in the chat to add a temporary API key for your session. * **`/ai apikey list`:** View your active session keys (masked for security). * **`/ai apikey clear`:** Remove all your active session keys. --- ## 🚀 How to Get Started 1. **Tame a Pet:** Tame a wolf, cat, or any other supported animal in Minecraft. 2. **Give it a Name:** Use a nametag to give your new companion a name. 3. **Link to the AI:** Look at your pet and type `/ai pet tame`. 4. **Give it a Nickname:** Use `/ai pet nickname <nickname>` to give your pet a unique nickname. 5. **Start Chatting!** Mention your pet's name or nickname in the chat to start a conversation. We are incredibly excited for you to try out the new Pet Emotional Communication System and form a deeper bond with your furry (and feathery) friends! --- ## 🛡️ Automatic Security & Bug Fixer Downloader NSR-AI now includes a robust, automated system to keep your plugin secure and up-to-date with the latest bug fixes. This system operates silently in the background, ensuring your server benefits from continuous improvements and protection without manual intervention for updates. ### How it Works: * **Automatic Security Updates:** The plugin periodically checks for updates to its security module. If a new version is available, it will be automatically downloaded and reloaded, ensuring your server always has the latest protections. * **Automated Bug Fixes:** The plugin also periodically checks for critical bug fixes for the main plugin. If a new bug fix is available, it will be automatically downloaded. * **Intelligent Version Tracking:** A dedicated `bug.txt` file tracks the installed bug-fix version, preventing redundant downloads and ensuring efficient updates. * **Server Restart for Main Plugin Updates:** For bug fixes that involve changes to the main plugin's core code, a server restart will be required to fully apply the update. The plugin will clearly notify you in the console when a restart is needed. * **Transparent Logging:** The system provides clear log messages in your server console, informing you about update checks, downloads, and when a restart is required. This ensures your NSR-AI experience is always stable, secure, and running the latest enhancements.

## NSR-AI v1.1 - Comprehensive Update This update introduces significant improvements to configuration management, and a powerful, multi-layered system for handling conversation history, designed for optimal performance and user control. --- ### Configuration Split For better organization and easier management, the plugin's configuration has been split into two distinct files: * **`config.yml`**: This file now contains the core settings for the plugin, such as: * Admin activation code * Default AI models (Gemini, Claude, OpenAI) * Default API provider * API keys * **`features.yml`**: This new file contains all feature-related settings, including: * Chat colors for the AI and users * Customizable messages for various events (e.g., API errors, permission denied) * The system prompt for the AI * Conversation history length * Chat prefixes for AI and users * Code blocker settings --- ### Advanced Memory & Caching System This system provides granular control over conversation history, balancing AI context with server performance. #### **1. Simple Session Caching (`/ai cache`)** These commands offer quick control over a player's active chat session without involving AI processing. They are ideal for fast resets. * **`/ai cache clear`** * **Action:** Instantly clears the AI's short-term memory for the specified target. * **Result:** The next message will start a completely fresh conversation. * **Usage:** * **Player:** `/ai cache clear` (Clears your own session) * **Admin:** `/ai cache clear <playername>` (Clears a specific player's session) * **Admin:** `/ai cache clear all` (Clears all online players' sessions) * **`/ai cache refresh`** * **Action:** Reloads the most recent conversation from the long-term log files back into the AI's short-term memory for the specified target. * **Result:** Allows continuation of a conversation that was previously cleared. * **Usage:** * **Player:** `/ai cache refresh` (Reloads your own session) * **Admin:** `/ai cache refresh <playername>` (Reloads a specific player's session) * **Admin:** `/ai cache refresh all` (Reloads all online players' sessions) #### **2. AI-Powered Memory (`/ai memory`)** This advanced feature uses AI to summarize and compress long conversations, enabling a nearly infinite memory while optimizing resource usage. * **`/ai memory clear` (Summarize and End Session)** * **Action:** The AI summarizes the current conversation history, and then the session is ended. * **Process:** The generated summary is saved to `summarieschat/`. If an old summary existed, it's archived into the main chat log. The AI's short-term memory is then cleared. * **Use Case:** To "bank" important information from a conversation as a summary before starting a new topic. * **Usage:** * **Player:** `/ai memory clear` (Summarizes and ends your own session) * **Admin:** `/ai memory clear <playername>` (Summarizes and ends a specific player's session) * **Admin:** `/ai memory clear all` (Summarizes and ends all online players' sessions) * **`/ai memory refresh` (Summarize and Continue Session)** * **Action:** The AI summarizes the current conversation history, and then replaces the detailed history with the summary, allowing the conversation to continue. * **Process:** The AI's short-term memory is replaced with a single system message containing the new summary. * **Result:** This frees up memory while allowing the AI to "remember" the context of the prior conversation in a compressed form, enabling very long and detailed interactions. * **Use Case:** To optimize memory during long, complex conversations without losing context. * **Usage:** * **Player:** `/ai memory refresh` (Summarizes and continues your own session) * **Admin:** `/ai memory refresh <playername>` (Summarizes and continues a specific player's session) * **Admin:** `/ai memory refresh all` (Summarizes and continues all online players' sessions) **Important Notes on AI-Powered Memory:** * **API Usage:** These commands will make calls to the AI API for summarization, incurring usage costs. * **Time:** Summarization is a complex task and may take a few moments to complete. These operations are asynchronous to prevent server lag. --- ### Persistent Chat Logging All conversations and generated summaries are automatically saved to disk, ensuring no chat history is lost. This process is asynchronous to maintain high server performance. * **Log Locations:** * Regular chats: `plugins/NSR-AI/playerchatshistory/` * Admin-mode chats: `plugins/NSR-AI/adminchatshistory/` * Latest summaries: `plugins/NSR-AI/summarychat/` --- ### Permissions * **Player Commands:** Any player can use `/ai cache clear/refresh` and `/ai memory clear/refresh` for themselves. * **Admin Commands:** Commands targeting other players or `all` require the user to be in admin mode. ## New Features Added to NSR-AI Plugin This update introduces several enhancements to the NSR-AI plugin, focusing on improved user experience and maintainability: * **Automatic Update Checker:** The plugin now includes an integrated update checker that automatically verifies if you are running the latest version upon startup. This helps ensure you always have access to the newest features and bug fixes. * **New In-Game Version Command:** A new command, `/ai version` (or `/ai v`), has been added. Players can use this command to: * View the current version of the plugin. * See if their plugin is up-to-date or if a newer version is available. * Access a list of features included in the latest available version. * **Outdated Version Notifications:** If your plugin is outdated, the server console will display a clear notification. Additionally, administrators will receive in-game messages with direct links to download the latest version from official platforms like Modrinth, SpigotMC, and Polymart. * **Cloudflare Worker Integration:** The update checking mechanism is powered by a Cloudflare Worker, ensuring efficient and reliable version verification. * **Enhanced Plugin Startup Message:** The plugin now features a more visually engaging startup message in the server console, presenting the plugin's name, version, and developer information in a clear and formatted manner. ## Recent Feature Enhancements This section outlines the latest additions and improvements to the NSR-AI plugin: * **Enhanced Command Set:** * **`/ai admin <activation_code>`:** A fully functional command to toggle administrator mode, allowing access to privileged commands. * **`/ai data <query>`:** This command now specifically queries the local knowledge base for answers, reducing reliance on external AI APIs for known information. * **`/ai add <keyword> <heading> <response>`:** Allows administrators to add new entries to the plugin's knowledge base directly in-game. * **`/ai remove <keyword>`:** Allows administrators to remove entries from the knowledge base directly in-game. * **`/ai reload`:** Enables administrators to reload the plugin's configuration without restarting the server. * **API Load Reduction:** Implemented a strategy to prioritize responses from the local knowledge base for `/ai data` commands, significantly reducing calls to external AI APIs and minimizing the "model overloaded" issues. * **Improved Plugin Lifecycle Messages:** The `onDisable()` message in the server console now provides more informative feedback, indicating whether the plugin disabled gracefully or due to errors. * **Enhanced `/ai add` command:** * New command structure: `/ai add <keyword>, <message_content>` * AI-generated headings for knowledge base entries based on `message_content`. * Preview of the knowledge entry (AI-generated heading and message to be saved) displayed to the admin before confirmation. * **Robust `/ai data` command:** * If the AI API call fails for `/ai data` queries, the plugin will now fall back to manually searching the local knowledge base and displaying relevant headings or content. * **Configurable Knowledge Base Output Color:** * New setting `chat-colors.knowledge-base` in `features.yml` to customize the color of knowledge base output. ## New Features (from latest update) This section details the very latest features and improvements: * **Symmetric `add` and `remove` commands:** When an admin removes data using `/ai remove <keyword>`, the plugin now displays the content of the removed entry, providing clear confirmation of the action. * **Improved Knowledge Base Search (`/ai data <query>`):** The `/ai data <query>` command has been significantly enhanced. It now searches not only the headings but also the *answers* (content) within the knowledge base. If a single, clear match is found, the answer is displayed directly. If multiple matches are found, the user is prompted to refine their query for more specific results. * **Direct Search Results Display:** When a clear match is found using `/ai data <query>`, the plugin now directly displays the answer from the knowledge base, rather than just the heading. * **Cleaned-up Heading Display:** When adding new knowledge entries, the "Heading (AI-generated):" prefix in the preview message has been removed for a cleaner and more concise output. * **New `/ai data all` Command:** A new command, `/ai data all`, has been introduced. This command allows administrators to view all entries currently stored in the knowledge base, including both their headings and content. * **Configurable Knowledge Confirmation:** A new setting, `simple-knowledge-yml-approve`, has been added to `features.yml`. This setting controls the confirmation method for adding new knowledge entries: * If `simple-knowledge-yml-approve` is set to `false` (default), the plugin will continue to provide a unique confirmation code that the admin must use with `/ai confirm <code>`. * If `simple-knowledge-yml-approve` is set to `true`, the plugin will simplify the confirmation process, requiring the admin to type `/ai confirm yes` to approve the addition. ## Granular Command Toggles This update introduces a highly granular command toggling system, allowing server administrators precise control over individual AI commands directly from the `features.yml` configuration file. Each command or command-related function can now be independently enabled or disabled. * **`command-toggles.data`**: Controls the `/ai data` and `/ai data all` commands. When set to `false`, players will be unable to use these commands to query the knowledge base. (Default: `true`) * **`command-toggles.admin`**: Controls the `/ai admin` command, which is used to toggle administrator mode. When set to `false`, administrators cannot use this command. (Default: `true`) * **`command-toggles.disable`**: Controls the `/ai disable` command, used to disable admin mode. When set to `false`, this command cannot be used. (Default: `true`) * **`command-toggles.version`**: Controls the `/ai version` (and `/ai v`) command, which displays plugin version information. When set to `false`, players cannot check the plugin's version. (Default: `true`) * **`command-toggles.add`**: Controls the `/ai add` command, used by administrators to add new entries to the knowledge base. When set to `false`, this command is unusable. (Default: `true`) * **`command-toggles.add-confirm`**: Controls the confirmation step for the `/ai add` command. * If `true` (default), administrators will be prompted to confirm the addition of a knowledge entry (either with a code or `/ai confirm yes`). * If `false`, knowledge entries added via `/ai add` will be instantly saved without requiring a separate confirmation step. * **`command-toggles.remove`**: Controls the `/ai remove` command, used by administrators to remove entries from the knowledge base. When set to `false`, this command is unusable. (Default: `true`) * **`command-toggles.remove-confirm`**: Controls the confirmation step for the `/ai remove` command. * If `true` (default), administrators will be prompted to confirm the removal of a knowledge entry (either with a code or `/ai confirm yes`). * If `false`, knowledge entries removed via `/ai remove` will be instantly deleted without requiring a separate confirmation step. * **`command-toggles.memory-clear`**: Controls the `/ai memory clear` command. When set to `false`, this command is unusable. (Default: `true`) * **`command-toggles.memory-refresh`**: Controls the `/ai memory refresh` command. When set to `false`, this command is unusable. (Default: `true`) * **`command-toggles.cache-clear`**: Controls the `/ai cache clear` command. When set to `false`, this command is unusable. (Default: `true`) * **`command-toggles.cache-refresh`**: Controls the `/ai cache refresh` command. When set to `false`, this command is unusable. (Default: `true`) ## Enhanced `/ai reload` Command This update significantly expands the functionality of the `/ai reload` command, providing more granular control over plugin reloads: * **`/ai reload` (default):** Reloads the main `config.yml`. * **`/ai reload c` or `/ai reload config`:** Reloads only the main `config.yml`. * **`/ai reload f` or `/ai reload features`:** Reloads only the `features.yml`. * **`/ai reload k` or `/ai reload knowledge`:** Reloads only the knowledge base. * **`/ai reload nsr-ai`:** Reloads the entire plugin (configs and knowledge base). ## New `/ai help` Command * **`/ai help`:** Displays a concise help message with descriptions for all available commands. This message dynamically adjusts to show only commands that are enabled in `features.yml` and accessible to the player (admin commands are only shown to administrators). * Typing `/ai` without any arguments now defaults to displaying this help message, making it easier for users to discover available commands. * **Tab Completion:** The plugin now supports intelligent tab completion for `/ai` commands, suggesting sub-commands and arguments based on context and enabled features. ## Addon Enhancements * **Backward Compatibility:** * The addon now supports both NSR-AI plugin version 1.1 and lower versions. This is achieved through a robust compatibility layer that uses reflection to adapt to different API versions at runtime. * **Enhanced Privacy Command (`/ai privacy`):** * **Non-Admins:** Can now use `/ai privacy <feature> [on|off]` to manage their *own* privacy settings without being prompted for a player name. * **Admins:** Can use `/ai privacy <player> <feature> [on|off]` to manage other players' privacy, or `/ai privacy <feature> [on|off]` to manage their own. * **Improved Tab Completion:** Basic tab completion for privacy features (`health`, `hunger`, etc.) and `on`/`off` options is now available. * **Player Data Initialization:** * The addon now ensures that player data is correctly initialized and saved when a player joins the server for the first time, preventing "no data" issues for new players. * **Detailed AFK Time Display:** * The `/ai stats` command now provides more detailed information for AFK status, displaying the duration a player has been AFK in minutes, seconds, hours, or days (e.g., "Yes (1h 30m)"). * **Version Update:** * The addon's internal version has been updated to `1.0.2`. ## Advanced Knowledge Base Search The knowledge base search has been significantly improved to provide more accurate and relevant results. * **Relevance-Based Scoring:** The search now uses a relevance scoring system to rank search results. This ensures that the most relevant entries are prioritized. * **Content and Heading Search:** The search now looks for matches in both the heading and the content of the knowledge base entries, providing more comprehensive results. * **Weighted Headings:** Matches found in the heading are given a higher weight, as they are more likely to be relevant. * **Fuzzy Search:** The search is now more tolerant of "irregular syntax" by splitting the query into individual words and searching for each word. * **Top 5 Results:** The search returns the top 5 most relevant results, making it easier for users to find the information they need.