Loreguard

┌────────────────────────────────────────────────────────────────────────────────┐
│                                                                                │
│  ██╗      ██████╗ ██████╗ ███████╗   ██████╗ ██╗   ██╗ █████╗ ██████╗ ██████╗  │
│  ██║     ██╔═══██╗██╔══██╗██╔════╝  ██╔════╝ ██║   ██║██╔══██╗██╔══██╗██╔══██╗ │
│  ██║     ██║   ██║██████╔╝█████╗    ██║  ███╗██║   ██║███████║██████╔╝██║  ██║ │
│  ██║     ██║   ██║██╔══██╗██╔══╝    ██║   ██║██║   ██║██╔══██║██╔══██╗██║  ██║ │
│  ███████╗╚██████╔╝██║  ██║███████╗  ╚██████╔╝╚██████╔╝██║  ██║██║  ██║██████╔╝ │
│  ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝   ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝  │
│                                                                                │
│  Local inference for your game NPCs                                            │
│  loreguard.com                                                                 │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

AI-Powered NPCs using your own hardware (your servers or your player's hardware) Loreguard CLI connects the LLM Inference to the Loreguard NPC system.

How It Works

┌─────────────────┐    wss://api.loreguard.com    ┌─────────────────┐
│   Your Game     │◄────────────────────────────► │  Loreguard API  │
│  (NPC Dialog)   │                               │    (Backend)    │
└─────────────────┘                               └────────┬────────┘
                                                           │
                                                           │ Routes inference
                                                           │ to your worker
                                                           ▼
                                                  ┌─────────────────┐
                                                  │  Loreguard CLI  │◄── You run this
                                                  │  (This repo)    │
                                                  └────────┬────────┘
                                                           │
                                                           │ Local inference
                                                           ▼
                                                  ┌─────────────────┐
                                                  │   llama.cpp     │
                                                  │  (Your GPU/CPU) │
                                                  └─────────────────┘

Installation

Linux / macOS

pip install loreguard-cli

Windows

Download loreguard.exe from Releases.

Or install via pip if you have Python:

pip install loreguard-cli

From Source

git clone https://github.com/beyond-logic-labs/loreguard-cli
cd loreguard-cli
pip install -e .

Quick Start

Interactive Mode (no arguments)

loreguard

The wizard guides you through:

1. Authentication - Enter your worker token
2. Model Selection - Choose or download a model
3. Running - Starts llama-server and connects to backend

Headless Mode (with arguments)

loreguard --token lg_worker_xxx --model /path/to/model.gguf

Or auto-download a supported model:

loreguard --token lg_worker_xxx --model-id qwen3-4b-instruct

Environment variables:

export LOREGUARD_TOKEN=lg_worker_xxx
export LOREGUARD_MODEL=/path/to/model.gguf
loreguard

Chat Mode (test NPC pipeline)

Test your NPC chat without running a local model:

loreguard --chat --token lg_worker_xxx

This connects directly to the Loreguard API to:

• List your registered NPCs
• Select one to chat with
• See verification status and latency

Supported Models

Works with any .gguf model. Tested with the following model families:

• Qwen - Recommended for best quality/speed balance
• Llama - Meta's open models
• GPT - GPT-style open models
• RNJ - Specialized models
• Violet Lotus - Community fine-tunes

Use any model with --model /path/to/model.gguf.

Concurrency (multi-slot)

A capable GPU can serve several NPC conversations at once. Two env vars control this:

• LOREGUARD_PARALLEL_SLOTS (default 1) — number of concurrent conversation slots (llama-server -np). Each slot holds one conversation's KV cache. Recommended on a 16 GB GPU: 8 (≈10 is the ceiling at ~4k-token sessions, ~8 at ~8k). Start at 4 and raise as you confirm VRAM (nvidia-smi) and throughput headroom. Don't over-provision — MoE models (e.g. Gemma) lose throughput when -np greatly exceeds real active concurrency.
• LOREGUARD_KV_CACHE_TYPE (default q8_0) — KV cache quantization. Keep q8_0; lower bit widths produce gibberish on Gemma.

export LOREGUARD_PARALLEL_SLOTS=8
export LOREGUARD_KV_CACHE_TYPE=q8_0
loreguard --token lg_worker_xxx --model-id gemma-3-27b

A slot serves one conversation per turn. Size LOREGUARD_PARALLEL_SLOTS at or above your expected peak concurrency: when all slots are busy, the engine waits briefly and then fails the extra turn (a clean error the game can retry) rather than corrupting a live conversation. Background memory passes borrow a free slot transiently and are skipped under saturation. Full benchmarks and sizing rationale: ADR-0035.

Use Cases

For Game Developers (Testing & Development)

Use Loreguard CLI during development to test NPC dialogs with your own hardware:

# Start the worker
loreguard-cli --token $YOUR_DEV_TOKEN --model-id qwen3-4b-instruct

# Your game connects to Loreguard API
# NPC inference requests are routed to your local worker

For Players (Coming Soon)

Note: Player distribution support is in development. Currently, players would need their own Loreguard account and token.

We're working on a Game Keys system that will allow:

• Developers to register their game and get a Game API Key
• Players to run the CLI without needing a Loreguard account
• Automatic worker provisioning scoped to each game

Interested in early access? Contact us at loreguard.com

Requirements

• RAM: 8GB minimum (16GB+ for larger models)
• GPU: Optional but recommended (NVIDIA CUDA or Apple Silicon)
• Disk: 2-6GB depending on model
• Python: 3.10+ (if installing from source)

Get Your Token

1. Go to loreguard.com/developers
2. Create a worker token
3. Use it with --token or LOREGUARD_TOKEN

Development

git clone https://github.com/beyond-logic-labs/loreguard-cli
cd loreguard-cli
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Run interactive wizard
python -m src.wizard

# Run headless CLI
python -m src.cli --help

# Run tests
pytest

License

MIT

See THIRD_PARTY_NOTICES.md for attribution and licenses of the machine learning models downloaded during setup.