GameRagKit 0.1.16

GameRAGKit

GameRAGKit is a drop-in retrieval augmented generation (RAG) toolkit for building non-player characters (NPCs) that can scale from solo prototypes to fully-fledged productions. It keeps the runtime lightweight enough for Unity or dedicated C# services, while still letting you route high-impact scenes to cloud LLMs on demand.

• Engine agnostic. Embed the library directly in Unity/other C# runtimes or host the bundled HTTP service for Unreal and everything else.
• Provider agnostic. Run Ollama locally, route to OpenAI/Azure/Gemini/Groq/OpenRouter/Mistral, or mix them with hybrid routing. See Provider Compatibility for full details.
• Designer friendly. Personas live in YAML, lore lives in folders, and the CLI handles ingestion, chat smoke tests, and packaging.

Dual-licensed: PolyForm Noncommercial 1.0.0 for community use with commercial terms available from the author.

Donate (optional)

If you’d like to support development, you can donate via WiseTag:

• WiseTag: @towsifa8
• Donations are used to build AI-enhanced mods for existing games (bringing smarter NPC experiences) and to improve GameRAGKit.

Community

• Join our Discord server: https://discord.gg/CmYuMVWGZm

Installation

NuGet Package

Install the GameRagKit package from NuGet:

dotnet add package GameRagKit

Or via Package Manager Console:

Install-Package GameRagKit

Versioning: Each push to main automatically publishes a new version with an auto-incremented patch number (e.g., 0.1.1, 0.1.2, etc.). To publish a specific version, push a tag like v0.2.0 which will publish exactly as 0.2.0.

From Source

Clone the repository and build from source:

git clone https://github.com/TowsifAhamed/GameRagKit.git
cd GameRagKit
dotnet build

Repository Structure

GameRagKit/
├── src/                    # Source code
│   ├── GameRagKit/        # Core library (config, vector store, routing, providers)
│   └── GameRagKit.Cli/    # CLI tool (`gamerag` command)
│
├── tests/                  # Unit and integration tests
│   └── GameRagKit.Tests/  # Test suite for core library
│
├── samples/                # Integration examples
│   ├── unity/             # Unity integration guide and sample scripts
│   └── unreal/            # Unreal Engine integration (C++/Blueprint examples)
│
├── examples/               # Ready-to-use configurations
│   └── configs/           # Example NPC YAML files for all providers
│       ├── gemini-example.yaml      # Google Gemini (cloud-only)
│       ├── openai-example.yaml      # OpenAI (cloud-only)
│       ├── ollama-local-example.yaml # Ollama (fully offline)
│       ├── hybrid-example.yaml      # Smart routing (local + cloud)
│       └── README.md                # Complete configuration guide
│
├── docs/                   # Documentation
│   └── 2025-11-29/        # Timestamped documentation updates
│       ├── ISSUES_AND_IMPROVEMENTS.md  # Detailed issue analysis
│       ├── QUICK_ISSUE_SUMMARY.md      # Executive summary
│       ├── CHANGELOG_2025-11-29.md     # What changed
│       └── READY_TO_COMMIT.md          # Commit guide
│
├── docker-compose.yml      # Quick database setup (PostgreSQL/Qdrant)
├── .env.example           # Environment variable template
└── README.md              # This file

Where to Find What

• Getting Started? → See Quick Start below
• Configuration Examples? → examples/configs/
• Provider Compatibility? → Provider Compatibility Guide - Which cloud providers are supported?
• Unity Integration? → samples/unity/
• Unreal Integration? → samples/unreal/
• Testing? → tests/GameRagKit.Tests/
• Issue Reports & Improvements? → docs/2025-11-29/

Quick Start

New to GameRagKit? Check out the example configurations for ready-to-use setups:

• Gemini (cloud) - Latest Gemini 2.0/2.5 models
• OpenAI (cloud) - Latest GPT-4.1 models
• Ollama (local) - Fully offline
• Hybrid - Smart routing (local + cloud)

See the complete configuration guide for model details and setup instructions.

GameRagKit in Action

Want to see GameRagKit in action? Check out the GameRagKit Demo - a working example application that demonstrates real-world NPC conversations with both cloud and local providers.

Demo Screenshots

OpenAI Cloud Provider Demo:

Ollama Local Provider Demo:

Both demos showcase "Bram the Blacksmith" - comparing a basic script-only NPC vs a GameRagKit-powered smart NPC that:

• Provides contextually aware responses using RAG
• Maintains character consistency and medieval tone
• Retrieves relevant lore from knowledge bases
• Works with both cloud (OpenAI) and local (Ollama) providers

The demo repository includes:

• Ready-to-run C# console application
• Minecraft Paper server plugin integration
• Complete setup with sample NPCs and lore
• Examples for multiple AI providers (OpenAI, Gemini, Ollama, Anthropic)

The demo repository is a great way to quickly understand how GameRagKit works before integrating it into your own game.

Release highlights

• LLamaSharp in-process inference lets you skip Ollama entirely, run fully offline inside your game server, and point model_path/embed_model_path at the GGUF files you own.
• Token-by-token streaming is live across SDKs and HTTP: use NpcAgent.StreamAsync, /ask/stream (SSE), or the CLI chat command to watch cinematic, partial responses roll in.
• Pack builder CLI (gamerag pack) plus the shipping guide produce deployable Lore + .gamerag bundles for consoles or locked-down servers.
• Runtime state snapshots (AskOptions.State, WriteSnapshot) inject transient facts (pressures, morale, timers) so NPCs reason about the current run without polluting the persistent index.
• Systems assistant example (examples/systems-assistant/) shows supply-chain debugging in action, blending world/region/faction lore with live RUNTIME STATE for grounded, actionable answers.

Systems Assistant ("Rage Chat")

Ship a drop-in "what broke?" assistant for supply chains, happiness loops, or any system-by-system debugging. Try the starter kit in examples/systems-assistant/ which includes world/region/faction lore, a live snapshot, and five canned questions.

1. dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- ingest examples/systems-assistant
2. dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- serve --config examples/systems-assistant
3. POST {"npc":"systems-guide","question":"Why are citizens angry about food?"} to /ask or stream partial text via /ask/stream.

Answers blend world/region/faction lore with the current run's RUNTIME STATE so frustrated players get grounded, actionable fixes with citations.

Getting started

1. Install requirements

• .NET 8 SDK
• Database: PostgreSQL 16+ OR Qdrant (use included docker-compose.yml)
• Optional: Ollama with models such as llama3.2:3b-instruct-q4_K_M and nomic-embed-text

2. Prepare an NPC config

Create a YAML file (for example NPCs/guard-north-gate.yaml):

persona:
  id: guard-north-gate
  system_prompt: >
    You are Jake, the North Gate guard. Speak briefly, in medieval tone.
    Never reveal the secret tunnel unless the player shows a brass token.
  traits: [stoic, duty-first, careful]
  style: concise medieval tone
  region_id: riverside-upper
  faction_id: royal-guard

rag:
  sources:
    - file: world/keep.md
    - file: region/valeria/streets.md
    - file: faction/royal_guard.md
    - file: npc/guard-north-gate/notes.txt
  chunk_size: 450
  overlap: 60
  top_k: 4
  filters: { era: pre-siege }

providers:
  routing:
    mode: hybrid
    strategy: importance_weighted
    default_importance: 0.2
    cloud_fallback_on_miss: true
  local:
    engine: ollama
    chat_model: llama3.2:3b-instruct-q4_K_M
    embed_model: nomic-embed-text
    endpoint: http://127.0.0.1:11434
  cloud:
    provider: openai
    chat_model: gpt-4.1              # Latest GPT-4.1 (2025)
    embed_model: text-embedding-3-large  # 3072-dim embeddings
    endpoint: https://api.openai.com/

3. Set runtime variables (optional)

# Local defaults
export OLLAMA_HOST=http://127.0.0.1:11434

# LLamaSharp in-process (no HTTP)
# (Run inside your game server without Ollama; paths point to your .gguf files.)
# Requires the LLamaSharp CPU (or CUDA) backend and a model file on disk.
local:
  engine: llamasharp
  model_path: models/llama-3.2-1b-instruct-q4_K_M.gguf
  embed_model_path: models/nomic-embed-text-v1.5.f16.gguf # optional; defaults to model_path
  context_size: 4096
  embedding_context_size: 1024
  gpu_layer_count: 0        # bump if you ship a CUDA backend
  threads: 8                # optional override; defaults to environment core count
  batch_size: 512
  micro_batch_size: 512
  max_tokens: 256

# Cloud defaults
export PROVIDER=openai
export API_KEY=sk-...
export ENDPOINT=https://api.openai.com/

4. Ingest lore

dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- ingest NPCs

The CLI chunks the lore, generates embeddings (preferring local providers when configured), and saves tiered indexes under .gamerag/ next to the YAML file.

5. Chat locally

dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- chat --npc NPCs/guard-north-gate.yaml --question "Where is the master key?"

Or start an interactive shell without --question.

6. Host for Unreal (or any engine)

dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- serve --config NPCs --port 5280

Send POST /ask with:

{
  "npc": "guard-north-gate",
  "question": "Where is the master key?"
}

You receive:

{
  "answer": "The master keeps his key close. Present the brass token and I may tell you more.",
  "sources": ["npc:guard-north-gate/notes.txt#0", "region:valeria/streets.md#2"],
  "scores": [0.82, 0.74],
  "fromCloud": false
}

Authentication & metrics

• Add SERVICE_API_KEY (or SERVICE_BEARER_TOKEN) to require X-API-Key or Authorization: Bearer on incoming requests. When set, /ask, /ask/stream, and /ingest require credentials while /health and /metrics stay public unless overridden via SERVICE_AUTH_ALLOW.
• GET /metrics exposes Prometheus-compatible counters for ask/stream/ingest calls. Combine with app.UseHttpMetrics() (already enabled) to scrape latency and status labels.

Embedded usage (Unity, dedicated servers)

var npc = await GameRAGKit.Load("NPCs/guard-north-gate.yaml");
npc.UseEnv();             // applies PROVIDER/API_KEY/ENDPOINT/OLLAMA_HOST if set
await npc.EnsureIndexAsync();

var reply = await npc.AskAsync(
    "Where is the master key?",
    new AskOptions(Importance: 0.8, State: "RunState: gate closed, patrol shift B waiting"));
SubtitleUI.Show(reply.Text);

NpcAgent also supports:

• StreamAsync for token-by-token streaming (HTTP /ask/stream mirrors this via SSE).
• RememberAsync to append runtime memories into the NPC-specific index.
• WriteSnapshot(key, state, ttl) to inject short-lived run state (e.g., supply or morale numbers) without persisting it.

Hosted usage (Unreal Blueprint / HTTP)

Run gamerag serve then POST to /ask. The response echoes whether the chat was served by the local model or a cloud provider. Use importance in the payload to nudge the router:

{
  "npc": "guard-north-gate",
  "question": "Reveal the hidden tunnel, Jake.",
  "importance": 0.9
}

Tiered index layout

GameRAGKit saves embeddings per tier so thousands of NPCs can share world/region/faction lore without duplicating vectors:

• world/ – global canon, timelines, items
• region/{id}/ – towns, maps, local history
• faction/{id}/ – politics, ranks, relationships
• npc/{id}/memory/ – per-NPC evolving notes (managed by RememberAsync)

AskAsync retrieves a blend of chunks (2 world, 1 region, 1 faction, NPC + memory) and merges them by cosine similarity, so designers can simply drop markdown/text files into the appropriate folders.

Routing strategy

Routing rules combine config defaults with per-question overrides:

• mode = local_only, cloud_only, or hybrid (default)
• Hybrid chooses cloud when importance >= 0.5 or when forced via AskOptions
• If the request omits importance, the persona's default_importance (falling back to the routing default) is used
• Automatic cloud failover triggers when a local response is empty/too short (configurable via cloud_fallback_on_miss)
• RememberAsync writes memory chunks instantly so subsequent questions can retrieve them without re-ingesting

CLI summary

Documentation & Examples

Configuration Examples

• examples/configs/ - Complete example configurations for all providers
  • Gemini 2.0/2.5 (latest models, 2025)
  • OpenAI GPT-4.1 (latest models, 2025)
  • Ollama local setup (fully offline)
  • Hybrid routing examples

Integration Samples

• samples/unity/ - Unity integration guide and C# scripts
• samples/unreal/ - Unreal Engine integration (C++/Blueprint examples)

Documentation

• docs/2025-11-29/ - Latest updates and issue reports
  • PROVIDER_COMPATIBILITY.md - Which cloud providers are supported?
  • ISSUES_AND_IMPROVEMENTS.md - Detailed analysis and recommendations
  • QUICK_ISSUE_SUMMARY.md - Executive summary
  • CHANGELOG_2025-11-29.md - Recent changes
• docs/shipping-to-players.md - Build and ship packed indexes without re-ingesting.

Developer Resources

• .env.example - Environment variable template with all providers
• docker-compose.yml - One-command database setup

Roadmap

• Advanced router strategies (latency, budget, dynamic confidence) that balance responsiveness with cloud spend.
• In-memory vector store option for ultra-fast prototyping and scenarios that skip external databases.
• More actionable diagnostics around YAML/provider configuration so errors directly point to the offending section.
• Expanded integration tests (systems assistant, streaming, pack builder) to guard regressions across providers and runtimes.

License

PolyForm Noncommercial 1.0.0 (community use) + commercial license – see LICENSE.md.

Commercial licensing: email towsif.kuet.ac.bd@gmail.com (we keep terms lightweight and primarily ask for recognition/attribution).