Skip to content

ERGS LLM AI Toolkit

The ERGS LLM Toolkit is a powerful integration layer for bringing Large Language Models (LLMs) into the physical escape room environment. It allows AI models to act as immersive NPCs (Non-Player Characters) that can "see" the game state through sensors and "act" upon the room via physical triggers.

Key Features

  • Universal API Support: A single parser interface for Ollama (local), Groq (high-speed), Google Gemini, and OpenAI.
  • Dynamic Context Injection: Real-time world data (variables, pressures, states) is automatically injected into the AI's "consciousness."
  • Action System (Tools): The AI can trigger physical room events (opening doors, activating fog, locking systems) using native Function Calling or a RegEx fallback system.
  • Story-Aware Guidance: Integrates with the ERGS Cue System to ensure the AI knows exactly what the players have achieved and what hints are currently relevant.

Component Architecture

1. LLM Model Node

The core processing unit. It handles the REST communication with the AI provider.

  • Inputs: Process (Action), History (Pointer).
  • Outputs: Response (Text), Tool (Action Name), Processing (Boolean).
  • Supported Endpoints: Custom URLs for local Ollama instances or cloud providers.

2. LLM Chat History Node

Manages the conversation buffer.

  • Configurable Buffer: Set the number of remembered messages (e.g., last 20 messages) to maintain performance and stay within token limits.
  • Role Management: Separates User input from Assistant responses.

3. LLM Property Node

Provides "Vision" to the AI. Connect any value from your ERGS graph to this node.

  • Description Template: Uses standard formatting (e.g., "Current oxygen level is %s percent") to explain the data to the LLM.
  • Automatic Injection: Values are bundled into the WORLD STATE section of the system prompt.

4. LLM Tool Node

Provides "Hands" to the AI.

  • Event Dispatcher: When the LLM decides to perform an action, the corresponding LLM Tool node fires an onEvent action in the ERGS graph.
  • Contextual Logic: Each tool has a description, telling the AI when and why it should be used.

Prompt Engineering & Structure

The toolkit uses a structured Multi-Block Prompt strategy to ensure the LLM follows instructions strictly while remaining in character:

  1. Persona: Defined in the Model Node Info property (Who is the AI?).
  2. Story Progression (Cues): Injected from the ERGS Cue System (What is happening?).
  3. World State (Properties): Real-time telemetry from sensors (What does the AI see?).
  4. Interaction Interface (Tools): Available physical actions (What can the AI do?).

Setup & Configuration

For High-Speed Performance (Groq / Gemini)

  1. Set the URL to the provider's completion endpoint.
  2. Provide the API Key.
  3. Set the Model Name (e.g., llama-3.1-8b-instant or gemini-1.5-flash-8b).
  4. The system automatically handles the Authorization or X-goog-api-key headers.

For Local Privacy (Ollama)

  1. Run Ollama locally.
  2. Set URL to http://localhost:11434/api/.
  3. Ensure tools supported is toggled based on the local model's capabilities.

Safety & Best Practices

  • Rate Limiting: The system includes a processing lock to prevent multiple simultaneous requests to the API.
  • Timeout Handling: Default 45s timeout ensures the game doesn't hang during cloud latency spikes.
  • Language Independence: While instructions are sent in English for better model adherence, the AI is instructed to always respond to players in the project's native language.