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. 🎮 ⚡ 🧠