callai-rpg 0.1.1__tar.gz

callai_rpg-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__
+.env*
+.pytest_cache
+*.log
+TODO.md
+upload
+library_lore.db
+savegame.json
+.blackboxrules
+.vscode
+venv
+build
+dist
+*.db

callai_rpg-0.1.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: callai-rpg
+Version: 0.1.1
+Summary: LLM-powered top-down RPG game
+Requires-Python: >=3.10
+Requires-Dist: asyncio
+Requires-Dist: pygame-ce>=2.5.0
+Requires-Dist: python-dotenv>=0.1.0
+Requires-Dist: websockets>=11.0.3
+Provides-Extra: hosting
+Requires-Dist: callai-agentic-core-rag[gemini]>=0.1.0; extra == 'hosting'
+Requires-Dist: callai-agentic-core[openai]>=0.6.6; extra == 'hosting'
+Description-Content-Type: text/markdown
+
+# My RPG (Multiplayer-Ready)
+
+A fully networked, Thick-Host/Thin-Client RPG engine driven by autonomous LLM agents. 
+
+## Run
+
+First, install dependencies:
+```bat
+pip install -r requirements.txt
+```
+
+### Multiplayer Mode
+
+**1. Start the Dedicated Host Server (Headless):**
+```bat
+python main.py --host
+```
+*(The server will start listening on `0.0.0.0:5555` by default).*
+
+**2. Start a Thin Client:**
+```bat
+python main.py --join 127.0.0.1
+```
+*(You can launch as many clients as you want. The server will dynamically assign them IDs like `remote_1`, `remote_2` and replicate the state).*
+
+### Singleplayer / Dev Mode (Local Bypass)
+To run the game locally without network serialization overhead:
+```bat
+python main.py
+```
+
+### Example
+
+#### Player 1 (The Host):
+1. Runs `python main.py --host`
+2. Opens a new terminal and runs an HTTP tunnel wrapper: `ngrok http 5555`
+3. Copies the forwarding URL provided by ngrok/your tunelling service (e.g., https://1234-abcd.ngrok-free.app).
+
+#### Player 2 (The Client):
+Runs `python main.py --join 1234-abcd.ngrok-free.app`
+(The engine automatically maps this to wss://1234-abcd.ngrok-free.app and successfully routes the TCP streams through the HTTPS tunnel).
+
+
+## LLM Setup
+
+
+### OpenAI (fallback)
+If Ollama fails to initialize, it falls back to `OpenAILLM()`.
+
+Set the following environment variables:
+
+- `OPENAI_API_KEY`
+- `OPENAI_BASE_URL` (optional; defaults to `https://api.openai.com/v1`)
+- `OPENAI_MODEL` (optional; required if OPENAI_BASE_URL is specified)
+
+You can place these in a local `.env` file, then specify their path: `python main.py --env-file .env'
+
+
+## Controls
+
+- **Arrows**: move player
+- **SPACE**: interact with nearby NPC, objects, doors, containers, and items. 
+- **ENTER**: Open a dialogue -> **Type** + **ENTER**: speak aloud, will be broadcasted to all nearby NPCs.
+> Note: For best performance, prefix your message to a specific NPC with '(To `npc_name`)', or Whisper to them via the interaction menu (must be standing close to them).
+
+- **TAB**: open inventory
+- *D*: drop the currently selected item in your inventory, will prompt a dialogue to specify amount to drop.
+- *L*: Global NPCs and event log.
+- **ESC**: close dialogue
+
+## Interaction options
+
+The following options are available in the interaction menu, subject to each object/entity type:
+
+- **NPCs**: Get their attention, Whisper to them, Give them gold
+- **Doors**: Openning them (if unlocked, or when the correct key is possessed in inventory when locked), Knock on them
+- **Containers**: Take away or Store items.
+- **Workstations/Harvestable objects** (e.g. trees): harvest/craft new items from them at the expense of some specific resources (if applicable).

callai_rpg-0.1.1/README.md

@@ -0,0 +1,78 @@
+# My RPG (Multiplayer-Ready)
+
+A fully networked, Thick-Host/Thin-Client RPG engine driven by autonomous LLM agents. 
+
+## Run
+
+First, install dependencies:
+```bat
+pip install -r requirements.txt
+```
+
+### Multiplayer Mode
+
+**1. Start the Dedicated Host Server (Headless):**
+```bat
+python main.py --host
+```
+*(The server will start listening on `0.0.0.0:5555` by default).*
+
+**2. Start a Thin Client:**
+```bat
+python main.py --join 127.0.0.1
+```
+*(You can launch as many clients as you want. The server will dynamically assign them IDs like `remote_1`, `remote_2` and replicate the state).*
+
+### Singleplayer / Dev Mode (Local Bypass)
+To run the game locally without network serialization overhead:
+```bat
+python main.py
+```
+
+### Example
+
+#### Player 1 (The Host):
+1. Runs `python main.py --host`
+2. Opens a new terminal and runs an HTTP tunnel wrapper: `ngrok http 5555`
+3. Copies the forwarding URL provided by ngrok/your tunelling service (e.g., https://1234-abcd.ngrok-free.app).
+
+#### Player 2 (The Client):
+Runs `python main.py --join 1234-abcd.ngrok-free.app`
+(The engine automatically maps this to wss://1234-abcd.ngrok-free.app and successfully routes the TCP streams through the HTTPS tunnel).
+
+
+## LLM Setup
+
+
+### OpenAI (fallback)
+If Ollama fails to initialize, it falls back to `OpenAILLM()`.
+
+Set the following environment variables:
+
+- `OPENAI_API_KEY`
+- `OPENAI_BASE_URL` (optional; defaults to `https://api.openai.com/v1`)
+- `OPENAI_MODEL` (optional; required if OPENAI_BASE_URL is specified)
+
+You can place these in a local `.env` file, then specify their path: `python main.py --env-file .env'
+
+
+## Controls
+
+- **Arrows**: move player
+- **SPACE**: interact with nearby NPC, objects, doors, containers, and items. 
+- **ENTER**: Open a dialogue -> **Type** + **ENTER**: speak aloud, will be broadcasted to all nearby NPCs.
+> Note: For best performance, prefix your message to a specific NPC with '(To `npc_name`)', or Whisper to them via the interaction menu (must be standing close to them).
+
+- **TAB**: open inventory
+- *D*: drop the currently selected item in your inventory, will prompt a dialogue to specify amount to drop.
+- *L*: Global NPCs and event log.
+- **ESC**: close dialogue
+
+## Interaction options
+
+The following options are available in the interaction menu, subject to each object/entity type:
+
+- **NPCs**: Get their attention, Whisper to them, Give them gold
+- **Doors**: Openning them (if unlocked, or when the correct key is possessed in inventory when locked), Knock on them
+- **Containers**: Take away or Store items.
+- **Workstations/Harvestable objects** (e.g. trees): harvest/craft new items from them at the expense of some specific resources (if applicable).

callai_rpg-0.1.1/docs/CONFIG_GUIDE.md

@@ -0,0 +1,57 @@
+### **Game Engine Configuration (`config.py`)**
+
+The configuration variables dictate the fundamental physics, AI boundaries, and survival mechanics of the game. They are grouped into specific sub-systems below.
+
+#### **1. Display & Environment**
+
+Controls the physical rendering window and base grid constraints.
+
+| Variable | Description |
+| --- |  --- |
+| **`WIDTH`** | The rendering window width in pixels. |
+| **`HEIGHT`** | The rendering window height in pixels. |
+| **`FPS`** | The target frames-per-second for the Pygame clock. |
+| **`TILE_SIZE`** | The pixel size of a single square grid tile. |
+
+#### **2. AI Priorities & Processing Limits**
+
+Determines how the `agentic_core` prioritizes events sent to the LLM queues to prevent minor events from blocking critical reactions. Lower numbers indicate higher priority.
+
+| Variable | Description |
+| --- | --- |
+| **`PRIO_COMBAT`** | Highest priority. Triggered when attacked or entering combat. |
+| **`PRIO_DIRECT_INTERACT`** | Triggered when a player or NPC directly speaks to, gives an item to, or knocks for the NPC. |
+| **`PRIO_SPEECH`** | General overheard dialogue from other characters. |
+| **`PRIO_OBSERVATION`** | Visual updates (e.g., someone enters/leaves the field of view). |
+| **`PRIO_IDLE`** | Lowest priority. Background thoughts or scheduled routine pings. |
+| **`LLM_MAX_CONCURRENT_REQUEST`** | The maximum number of simultaneous API calls allowed. |
+| **`LLM_INTERRUPT_PRIORITY_THRESHOLD`** | Events with this priority or lower will instantly cancel an ongoing LLM generation task. |
+
+#### **3. Vision, Senses & Interaction Limits**
+
+Defines the spatial awareness of NPCs. Distances are calculated in tiles.
+
+| Variable | Description |
+| --- | --- |
+| **`VISION_RANGE_TILE`**  | The maximum radius an NPC can detect entities or items. |
+| **`ROOM_VISIBLE_RANGE_TILE`**  | How far an NPC can "see" a room's center to know it exists. |
+| **`SPEECH_OBSERVATION_RADIUS_TILE`**  | The maximum distance text chat can be "heard" by others. |
+| **`PHYSICAL_INTERACTION_RADIUS_TILE`**  | The distance an NPC will notice environmental changes (doors opening, items dropping). |
+| **`GIVE_MAX_DISTANCE_TILE`**  | Maximum distance allowed to execute the `give_item` or `give_gold` tools. |
+| **`WHISPER_MAX_DISTANCE_TILE`**  | Maximum distance to execute a private `whisper` tool. |
+| **`COMBAT_STRIKE_DISTANCE_TILE`** | The physical proximity required to land a melee attack. |
+| **`KNOCK_SOUND_BASE`**  | Base radius of a knock sound, scaling inversely with room occupants. |
+
+#### **4. NPC Behavior & The Maslow Engine**
+
+Controls the physiological needs, patience, and scheduling of the autonomous agents.
+
+| Variable | Description |
+| --- | --- |
+| **`TIME_SCALE`** | 1 real-world second equals 60 in-game seconds (1 real minute = 1 in-game hour). |
+| **`NEEDS_DECAY_RATE_PER_MIN`** | Hunger increases and energy decreases by 0.1 every in-game minute. |
+| **`CHAOS_TICK_INTERVAL_SEC`** | Frequency (in real seconds) of pinging off-screen NPCs to force background simulation. |
+| **`NPC_WAIT_AFTER_ARRIVAL_SEC`** | How long an NPC pauses after reaching a destination before determining their next move. |
+| **`NPC_PATIENCE_WAIT_SEC`** | How long an NPC will wait for a response after handing an item or speaking to someone. |
+| **`HIBERNATE_DISTANCE_TILES`** | Distance from the player at which an NPC stops active rendering/processing and enters a sleep state. |
+

callai_rpg-0.1.1/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "callai-rpg"
+version = "0.1.1"
+description = "LLM-powered top-down RPG game"
+requires-python = ">=3.10"
+readme = "README.md"
+dependencies = [
+  "pygame-ce>=2.5.0",
+  "asyncio",
+  "websockets>=11.0.3",
+  "python-dotenv>=0.1.0"
+]
+
+[project.scripts]
+carpg = "rpg.cli.main:main"
+
+[project.optional-dependencies]
+hosting = [
+  "callai-agentic_core[openai]>=0.6.6",
+  "callai-agentic_core-rag[gemini]>=0.1.0"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rpg"]

callai_rpg-0.1.1/requirements.txt

@@ -0,0 +1,3 @@
+pygame-ce>=2.5.0
+asyncio
+websockets>=11.0.3

callai_rpg-0.1.1/rpg/__init__.py

@@ -0,0 +1,5 @@
+"""RPG package extracted from the original monolithic main.py.
+
+Keep root main.py as a compatibility facade for existing imports.
+"""
+

callai_rpg-0.1.1/rpg/ai/event_handler.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import queue
+import re
+import logging
+
+from ..core.types import GameAction
+
+import time
+from agentic_core.handlers.standard import SmartRetryHandler
+from agentic_core.decisions import ErrorDecision, DecisionEvent
+
+logger = logging.getLogger(__name__)
+
+# Global state to stagger API retries and prevent Thundering Herd DDoS
+GLOBAL_API_BACKOFF_UNTIL = 0.0
+
+def clean_speech(text: str) -> str:
+    """Strip emoji, non-printable characters, and RP action annotations."""
+    # 0. Heuristic XML extraction: If the model wrapped the actual speech in a tag
+    xml_match = re.search(r'<(speech|dialogue|message|say|text)\b[^>]*>(.*?)</\1>', text, flags=re.IGNORECASE | re.DOTALL)
+    if xml_match:
+        cleaned_text = xml_match.group(2)
+        if cleaned_text: text = cleaned_text
+        
+    # Strip any remaining loose XML/HTML-like tags (e.g. leaked <thought> blocks)
+    text = re.sub(r'<[a-zA-Z\/][^>]*>', '', text)
+    
+    # 1. Strip emojis and non-printables
+    text = re.sub(r"[^\x20-\x7E]", "", text)
+    
+    # 2. Strip *asterisk* RP actions (e.g., *smiles*, *walks away*)
+    text = re.sub(r'\*[^*]+\*', '', text)
+
+    # 3. Strip [bracket] RP actions
+    text = re.sub(r'\[[^\]]+\]', '', text)
+    
+    # 4. Strip (parentheses) RP actions, BUT preserve conversation targeting like "(To Alice)"
+    # Using negative lookahead to ignore if it starts with "To " or "to "
+    text = re.sub(r'\((?![Tt]o\s)[^)]+\)', '', text)
+    
+    # 5. Clean up weird double spaces left behind by the regex
+    text = re.sub(r'\s{2,}', ' ', text)
+    
+    return text.strip()
+
+import json
+class PrettyDict(str):
+    """A dictionary that automatically strings itself with beautiful formatting."""
+    def __str__(self):
+        try:
+            placeholder = json.loads(self)
+            # indent=4 creates the nesting, sort_keys keeps it predictable
+            return json.dumps(placeholder, indent=4, ensure_ascii=False, default=str)
+        except Exception:
+            return super()
+
+    def __repr__(self):
+        return self.__str__()
+    
+class PygameEventHandler(SmartRetryHandler):
+    """Bridges agentic_core events back into the game thread via game_action_queue."""
+
+    def __init__(self, npc_id: int, game_action_queue: queue.Queue, npc_name: str | None = None):
+        # Configure exponential backoff: up to 4 retries, starting at a 2.0s delay
+        super().__init__(max_retries=4, base_delay=2.0)
+        self.npc_name = npc_name
+        self.npc_id = npc_id
+        self.game_action_queue = game_action_queue
+        self.has_used_tool = False
+        self.has_spoken_this_turn = False
+
+        self.active_tool_calls = {}
+
+    async def on_turn_start(self) -> None:
+        self.has_used_tool = False
+        self.has_spoken_this_turn = False
+        return
+
+    async def on_tool_start(self, tool_name: str, tool_id: str, tool_arg=None):
+        arg_display = str(PrettyDict(tool_arg)) if tool_arg else "{}"
+        self.active_tool_calls[tool_id] = arg_display
+        return await super().on_tool_start(tool_name, tool_id, tool_arg)
+
+    async def on_tool_complete(self, tool_name: str, tool_id: str, success: bool, result: str) -> None:
+        logger.info(f"\n=============\n\n{self.npc_name}: '{tool_name}'\nArguments: {self.active_tool_calls[tool_id]}\nResult: {result}\n\n=============")
+        self.has_used_tool = True
+        
+        # Clear speech debounce so post-tool dialogue appears instantly
+        self.game_action_queue.put(GameAction(npc_id=self.npc_id, action_type="clear_speech_timer"))
+        
+        return
+
+    async def on_turn_complete(self, response) -> None:
+        text = ""
+        try:
+            text = response.text.strip()
+        except Exception:
+            text = "(LLM produced invalid response, please try again.)"
+            return
+
+        text = clean_speech(text)
+        
+        # --- Filter out silence indicators ---
+        if text.lower() in ("...", "silence", "*silence*", "*nods*", "*waits*", '""', "''"):
+            text = ""
+
+        if text:
+            self.game_action_queue.put(
+                GameAction(npc_id=self.npc_id, action_type="speak", payload=text)
+            )
+
+        # Send debug info back to main thread
+        tool_calls_str = ", ".join([tc['function']['name'] for tc in response.tool_calls]) if response.tool_calls else "None"
+        reasoning_str = response.reasoning if response.reasoning else "(No reasoning provided)"
+        self.game_action_queue.put(
+            GameAction(npc_id=self.npc_id, action_type="update_debug_state", payload={
+                "reasoning": reasoning_str,
+                "tool_calls": tool_calls_str
+            })
+        )
+
+    async def on_error(self, error_context):
+        err = error_context.error
+        
+        # Provider Infrastructure Bug Catcher:
+        # If the provider sends malformed SSE chunks (often a hidden rate limit or concurrency choke),
+        # force the engine to treat it as a transient error and back off.
+        if err and "JSONDecodeError" in type(err).__name__:
+            if error_context.retry_count < self.max_retries:
+                decision = DecisionEvent(action=ErrorDecision.RETRY(delay=self.base_delay, exponential_base=2.0))
+            else:
+                decision = DecisionEvent(action=ErrorDecision.ABANDON())
+        else:
+            # 1. Let the SmartRetryHandler decide if this is a transient error (RateLimit/Timeout)
+            decision = await super().on_error(error_context)
+        
+        # 2. If it decided to retry with backoff, apply global staggering
+        if isinstance(decision.action, ErrorDecision.RETRY):
+            global GLOBAL_API_BACKOFF_UNTIL
+            now = time.time()
+            
+            # If the global backoff is already in the future, add our delay on top to stagger
+            if now < GLOBAL_API_BACKOFF_UNTIL:
+                decision.action.delay += (GLOBAL_API_BACKOFF_UNTIL - now)
+                GLOBAL_API_BACKOFF_UNTIL += decision.action.delay
+            else:
+                GLOBAL_API_BACKOFF_UNTIL = now + decision.action.delay
+                
+            logger.info(f"NPC {self.npc_name} API call failed. Staggering retry by {decision.action.delay:.1f}s...")
+            return decision
+            
+        # 3. If it's a fatal error (Auth error, max retries exceeded, etc.), log it to the HUD
+        try:
+            err = str(getattr(error_context, "error", "Unknown error"))
+        except Exception:
+            err = "Unknown error"
+
+        # Route to HUD instead of shouting out loud
+        self.game_action_queue.put(
+            GameAction(npc_id=self.npc_id, action_type="log_error", payload=err)
+        )
+
+        import traceback
+        if hasattr(error_context, "error") and error_context.error is not None:
+            error_list = traceback.format_exception(type(error_context.error), error_context.error, error_context.error.__traceback__)
+            error_string = "".join(error_list)
+            logger.warning(f"Fatal LLM error for NPC {self.npc_id}: {error_string}")
+
+        return decision