AI Assistant Reference & User Guide: RPG Agent Proxy

This document serves as an all-in-one guide and reference instruction set. If you are an AI assistant helping a user deploy, configure, or troubleshoot the RPG Agent Proxy, use the context and instructions below.

1. Overview & Core Features

The RPG Agent Proxy is a FastAPI server that acts as a middleware bridge between chat clients (like JanitorAI, SillyTavern, or any OpenAI-compatible frontend) and OpenRouter.

It intercepts payloads to provide:

1. Stateful Roleplay (Session Cache): Maintains character stats, inventory, and quest variables in a per-session JSON file.
2. State Injection (Read Optimization): Automatically serializes and injects the current game state into the LLM's system instructions dynamically at each iteration.
3. Restricted Python Sandbox (Write Optimization): Allows the LLM to run math, damage calculations, and update stats by writing Python code executed in a subprocess.
4. True Random Dice Rolling: Prevents hallucinated dice outcomes using programmatic rolling tools.
5. Branching Path Safety: Uses a cryptographic turn-key hash to prevent state corruption when users "Retry" or edit history.

2. Local Setup & Execution Guide

Prerequisites

• Python 3.12+
• An OpenRouter API key

Installation Steps

1. Clone the Repository:

   git clone <repository-url>
   cd rpg-agent-behind-chat-completion
   

2. Initialize the Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate
   pip install -e .
   

3. Configure Environment Variables: Copy the example template and fill in your API key:

   cp .env.example .env
   

   Open .env and set:

   • OPENROUTER_API_KEY=your_openrouter_api_key_here
   • (Optional) RPG_AGENT_PROXY_KEY=your_custom_password (If omitted, a random key is generated at startup and written to proxy.key).

4. Run the Server:

   PYTHONPATH=src uvicorn rpg_agent.proxy:app --host 0.0.0.0 --port 8000 --reload
   

5. Find the API key: Look at the server startup logs or open the newly created proxy.key file in the repository root.

3. Hugging Face Spaces Deployment Guide

To deploy this project to Hugging Face Spaces for free:

Step 1: Create the Space

1. Go to the Hugging Face website and create a new Space.
2. SDK: Select Docker.
3. Template: Select Blank (no template).
4. Hardware: Choose CPU Basic (Free tier).
5. Visibility: Private (recommended to keep your keys secure!).

Step 2: Configure secrets

In your Space page, navigate to Settings -> Variables and secrets and add:

• OPENROUTER_API_KEY (Required): Your OpenRouter API key.
• RPG_AGENT_PROXY_KEY (Optional): A custom access password.

Step 3: Push the code

Add the Space as a git remote and push the main branch:

git remote add hf https://huggingface.co/spaces/<your-username>/<space-name>
git push -f hf main

Note: Hugging Face will read the Dockerfile and automatically build your container on port 7860.

Step 4: Retrieve key

If you did not define a custom RPG_AGENT_PROXY_KEY in step 2:

1. Go to your Space page and click the Logs tab.
2. Look for the startup output containing the auto-generated proxy key.

4. Chat Client Configuration (JanitorAI / SillyTavern)

Point your chat client's API settings at the running proxy server:

Variant A: Local Server

• API URL: http://localhost:8000/v1 (or http://127.0.0.1:8000/v1)
• API Key: The contents of proxy.key (or your custom RPG_AGENT_PROXY_KEY).

Variant B: Public / Resumed Hugging Face Space

• API URL: https://<your-username>-<space-name>.hf.space/v1
• API Key: The auto-generated key from the Space logs (or your custom RPG_AGENT_PROXY_KEY).

Variant C: Private Hugging Face Space (Single-Token Setup)

Because private Spaces block edge traffic, you must supply your personal Hugging Face access token to reach the Space. To avoid header conflicts:

1. In your private Hugging Face Space settings, add the secret RPG_AGENT_PROXY_KEY and set its value to your Hugging Face User Access Token (hf_...).
2. Configure your chat client as follows:
   • API URL: https://<your-username>-<space-name>.hf.space/v1
   • API Key: <YOUR_HUGGINGFACE_USER_ACCESS_TOKEN>
3. How this works: The single token satisfies both the Hugging Face gateway (at the edge) and the proxy app (inside the container).

5. Session State & Config Tuning

Session Resolution Hierarchy

The proxy automatically groups conversation turns into sessions. It resolves the session_id using this priority hierarchy:

1. Explicit: URL path segment (e.g. /v1/{session_id}/chat/completions) or query parameter ?session_id=....
2. OOC Tag: Scans messages (newest first) for a [session: name] tag.
3. Hash Fallback: Computes a hash of the system prompt + persona username of the last user message.

Adjusting configs.yaml

You can modify configs.yaml to customize proxy limits:

• num_states_to_track (Default: 128): Controls how many turns of history to cache per session. Higher values allow longer retries but use more disk space.
• timeout_seconds (Default: 12.0): The hard execution timeout for the Python sandbox. 12 seconds is recommended for CPU-constrained containers like Hugging Face.
• max_iterations (Default: 5): Maximum tool-calling steps the agent can run in a single chat turn. Prevents infinite reasoning loops.

{{user}} seeks guidance regarding how to set up RAB-CC with {{poss}} janitorAI interface.