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.
5. 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: 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.
5. 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.(note that current plugin bug version will may have bugs and all

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.2-Beta - 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 <key> 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 in the normal chat paste <key> not in the command): 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.

# NSR-AI Plugin - Features (Version 1.1-pre2)

This document provides a detailed description of the features available in the NSR-AI Plugin.

## Core Features

- **AI-Powered Chat:** Engage in intelligent conversations with an AI directly in your Minecraft server.
- **Knowledge Base:** A powerful system to store and retrieve server-specific information, such as rules, event details, and FAQs.
- **Admin Mode:** A dedicated mode for server administrators with access to advanced commands and features.

## Command Structure

- **`/ai <message>`:** For general AI conversations.
- **`/ai data <question>`:** To query the knowledge base for specific information.
- **`/ai admin <your_activation_code>`:** To activate admin mode.
- **`/ai disable`:** To deactivate admin mode.

## Knowledge Base Management (Admin-Only)

- **`/ai add <content>`:** Add new information to the knowledge base. The AI will automatically correct grammar and spelling.
- **`/ai remove <question>`:** Remove entries from the knowledge base.
- **`/ai confirm <code> [keyword]`:** Confirm the addition or removal of knowledge base entries.

## Advanced Features

- **AI-Generated Headings:** When adding to the knowledge base, the AI generates descriptive headings for better organization.
- **Enhanced Fuzzy Matching:** The knowledge base search uses a smart matching algorithm to find relevant information even with varied phrasing.
- **Confirmation System:** A secure, 6-digit code confirmation system for all knowledge base modifications.
- **Automatic Reload:** The knowledge base is automatically reloaded after any changes, ensuring information is always up-to-date.
- **Robust and Stable:** Asynchronous API calls prevent server lag, and a retry mechanism for API calls improves reliability.
- **Clean Chat History:** Chat history is saved in a clean, easy-to-read format.

## How to Use the Knowledge Base

1. **Activate Admin Mode:** `/ai admin <your_activation_code>`
2. **Add Information:**
- `/ai add <content>` (e.g., `/ai add The server rules are available on our website at example.com/rules.`)
- The AI will provide a corrected version of your text and a 6-digit confirmation code.
3. **Confirm Addition:**
- `/ai confirm <code> <keyword>` (e.g., `/ai confirm 123456 rules`)
- The information is now permanently stored in the knowledge base.
4. **Query the Knowledge Base:**
- `/ai data <question>` (e.g., `/ai data what are the server rules?`)
- The AI will retrieve and display the relevant information.

Version 1.1-pre1
New feature personalized greetings and responses using your
player name.
example: if you asked what is my name or anything else
it may response with your name depend on question you asked

Multi-API Support

• Description: The plugin now supports multiple AI APIs, including Gemini, Claude, and OpenAI. This allows you to choose the AI provider that best suits your needs in terms of performance, cost, and features.
• Configuration: You can configure the default API provider and add your API keys in the `config.yml` file.

Code Blocker

• Description: A new security feature that prevents the AI from providing code snippets in its responses. This is to prevent the AI from being used to generate malicious code that could harm the server or its players.
• Configuration: The Code Blocker can be enabled or disabled in the `config.yml` file, and the message that is displayed to the player when a code snippet is detected can also be configured.

Addon Support

• Description: The plugin now has a powerful addon system that allows for extending its functionality with new features and commands. This modular approach makes it easy to customize the plugin to your server's specific needs.
• Directory Tree: Addons are placed in the `plugins/NSR-AI/addons` directory.

Advanced Player Stats Addon

• Description: A new addon that provides a wide range of features for tracking and displaying player statistics.
• Features:
  • In-Depth Player Statistics: Track a wide range of player stats, including playtime, kills, deaths, blocks mined, and more.
  • Per-Player Privacy: A comprehensive privacy system that allows players to control who can see their stats.
  • AFK Tracker: Automatically detects when a player is AFK and notifies administrators.
  • Natural Language Commands: Use more natural and intuitive commands to interact with the addon.
  • "Did you mean?" for Player Names: Corrects spelling mistakes in player names to make commands easier to use.

Key Features in NSR-AI v1.0.1

• Persistent Knowledge Base
  Admins can now “teach” the AI specific facts or responses using simple commands. These custom responses are saved locally and triggered when a player’s question matches a defined keyword — providing accurate, server-specific answers. This system works independently of the external AI API.
  
  
• Enhanced API Error Reporting
  When something goes wrong while contacting the Gemini API, the plugin now returns more detailed and helpful error messages, making it easier for server owners to troubleshoot issues.
  
  
• AI Self-Awareness
  The AI can now respond intelligently to questions like “Who are you?” or “What do you do?”, giving players a predefined answer about its identity and purpose on the server.
  
  
• ⚡ Optimized API Response Time
  API call timeouts have been fine-tuned to 10 seconds, helping reduce lag and ensuring players get faster replies from the AI.
  
  
• Customizable Chat Prefixes
  Server owners have full control over chat prefixes. You can now define unique tags for:
  
  • AI responses in normal mode
    
    
  • Player messages
    
    
  • AI responses in admin mode
    
• Quick Admin Mode Deactivation
  Admins can now exit admin mode instantly by simply sneaking (crouching) in-game, in addition to disconnecting. This makes toggling special admin features much easier during gameplay.