Nighthawk/VDM
1
0
Fork 0
mirror of https://github.com/Nighthawk42/VDM.git synced 2026-08-30 04:30:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Moved to uv managed venv

Browse Source
This commit is contained in:
Nighthawk
2025-09-05 08:09:03 -04:00
parent 97df43ce91
commit ec66e77cac
18 changed files with 103 additions and 429 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+58 -42
View File
@@ -14,7 +14,7 @@ The project is built with a focus on stability and cutting-edge features, levera
* **AI-Powered Game Master:** A sophisticated LLM acts as the storyteller, reacting to player actions, describing the world, and narrating events.
* **Real-Time Multiplayer:** Join a room with friends from anywhere. The game state is synchronized in real-time for a seamless collaborative experience.
* **Turn-Based System:** A structured turn system allows players to declare their actions, which are then submitted to the GM as a single turn for resolution.
* **Session Persistence:** Save your game with the `/save` command. The server automatically reloads your session when you rejoin the room.
* **Permanent Room Ownership**: The first player to create a room becomes its permanent owner, ensuring they always have host controls when they rejoin.
### Advanced AI Memory
* **State-of-the-Art RAG Pipeline:** The AI has a true long-term memory, powered by Google's **EmbeddingGemma** model for top-tier embeddings and the **Chonkie** library for intelligent semantic chunking.
@@ -24,18 +24,19 @@ The project is built with a focus on stability and cutting-edge features, levera
### Immersive Experience
* **High-Quality Voice Narration:** The GM's responses are brought to life with server-side Text-to-Speech using the `kokoro` library.
* **Speech-to-Text Input:** A "Hold to Talk" microphone button allows players to speak their actions instead of typing.
* **Markdown Rendering:** GM and player messages are rendered with Markdown for better formatting and readability (e.g., *italics* and **bold**).
* **Markdown Rendering:** Chat messages are rendered with Markdown for rich text formatting (*italics*, **bold**).
### Modern UI/UX
* **Clean & Responsive Interface:** A modern single-page application that works on any device.
* **Light/Dark Modes:** A persistent theme toggle for user comfort.
* **Modular Frontend:** The JavaScript is broken down into small, maintainable modules for features like auth, commands, and avatars.
* **Modular Frontend:** The JavaScript is broken down into small, maintainable modules.
* **Visual Turn Indicator:** See at a glance which players have submitted their action for the current turn.
### Robust Backend
* **Pluggable AI Backends:** Easily switch between different LLM providers, including local options like **LM Studio** and **Ollama**, or cloud services like **OpenRouter**.
* **Modern Python Packaging**: Uses a `pyproject.toml` file and a `src` layout, following the latest Python standards.
* **Pluggable AI Backends:** Easily switch between different LLM providers (LM Studio, Ollama, OpenRouter).
* **Secure User Accounts:** Player accounts are stored with hashed passwords in a dedicated SQLite database.
* **Persistent Sessions:** User logins survive server restarts, allowing for a seamless reconnection experience.
* **Persistent Sessions:** User logins survive server restarts for a seamless reconnection experience.
---
@@ -45,55 +46,70 @@ Follow these steps to get your VDM server up and running.
### Prerequisites
* **Python 3.11+**
* **`uv`**: A fast Python package installer. If you don't have it, run:
```bash
pip install uv
```
* **(Optional) NVIDIA GPU**: For the best performance with local LLMs and TTS.
* **Python 3.11 or higher** installed on your system.
* **`uv`**: A fast Python package manager. If you don't have it, run:
```bash
pip install uv
```
### 1. Project Setup
---
First, clone or download the project repository.
### 1. Setup and Environment Activation
### 2. Create and Activate the Virtual Environment
Open your terminal in the project's root directory and run:
Open your terminal and run the following commands from the directory where you want to store the project.
```bash
# Create the virtual environment
uv venv
# 1. Clone the project repository
git clone https://github.com/Nighthawk42/VDM.git
cd VDM
# Activate the environment
# 2. Create a seeded virtual environment with Python 3.11 (required step)
uv venv --seed --python 3.11
# 3. Activate the new environment
# On Windows:
.venv\Scripts\activate
# On macOS / Linux:
# source .venv/bin/activate
```
### 3. Install Dependencies
---
Install all required Python packages. **Note:** This step will download large AI models for embeddings and TTS, which may take some time.
### 2. Install Dependencies
This project can be run on a CPU, but an NVIDIA GPU is highly recommended for the best performance. Choose one of the following installation options.
**For NVIDIA GPU Systems (Recommended):**
```bash
uv pip install ".[gpu]" --extra-index-url https://download.pytorch.org/whl/cu121
```
**For CPU-Only Systems:**
```bash
uv pip install .
```
> **Note:** This step will download large AI models for embeddings and TTS, which may take some time.
---
### 3. Configure the VDM
* **Environment Variables**: Copy `.env.example` to `.env` and fill in any necessary API keys or change the default URLs for your local LLM providers.
* **Main Configuration**: Open `settings.yml` to configure the core behavior, especially the `llm` and `memory` sections.
* **Prompts (Optional)**: Edit `prompts.yml` to change the GM's personality.
---
### 4. Launch the Server!
Simply run the launch script.
```bash
uv pip install -r requirements.txt
uv run uvicorn vdm_server.main:app --reload --reload-dir ./src/vdm_server --reload-dir ./web --host 127.0.0.1 --port 8000
```
### 4. Configure the VDM
* **Environment Variables**: Copy `.env.example` to `.env` and fill in any necessary API keys or change the default URLs for your local LLM providers.
* **Main Configuration**: Open `settings.yml` to configure the core behavior, especially the `llm` and `memory` sections to select your AI backend and chunking strategy.
* **Prompts & Voices (Optional)**: Edit `prompts.yml` to change the GM's personality or `voices.yml` for dynamic voice casting.
### 5. Launch the Server!
Simply run the launch script. It will activate the environment and start the Uvicorn server.
```cmd
uvicorn server.main:app --reload --reload-dir ./server --reload-dir ./web --host 127.0.0.1 --port 8000
```
The server will be running at `http://127.0.0.1:8000`. You and your friends can now connect and play!
The server will be running at `http://127.0.0.1:8000`.
---
@@ -111,8 +127,8 @@ The server will be running at `http://127.0.0.1:8000`. You and your friends can
## ⌨️ Slash Commands
* `/roll [dice]`: Rolls dice (e.g., `/roll 2d6+3`). Defaults to `1d20`.
* `/ooc [message]`: Sends an out-of-character message to other players.
* `/remember [fact]`: Saves a critical fact to the GM's long-term memory.
* `/save`: Saves the current game session.
* `/next`: Submits the current turn's actions to the GM.
* `/roll [dice]`: Rolls dice (e.g., `/roll 2d6+3`). Defaults to `1d20`.
* `/ooc [message]`: Sends an out-of-character message to other players.
* `/remember [fact]`: Saves a critical fact to the GM's long-term memory.
* `/save`: Saves the current game session.
* `/next`: Submits the current turn's actions to the GM.