feat: add .env.sample and update README for USE_MODAL configuration

.env.sample

@@ -0,0 +1 @@
+USE_MODAL=false

README.md

@@ -21,17 +21,21 @@ Check out the configuration reference at <https://huggingface.co/docs/hub/spaces
 ### Setup
 
 ```sh
+cp .env.sample .env
 uv sync --frozen
 ```
 
 ### Modal
 
-If your local GPU is not powerful enough to run the model, you can deploy it to Modal 🚀
+If your local GPU is not powerful enough to run "gpt-oss-20b", you can deploy it to Modal 🚀
 
 ```sh
+uv run modal setup
 uv run modal deploy src/unpredictable_lord/llm_modal.py
 ```
 
+and then set `USE_MODAL=true` in your `.env` file.
+
 ### Run locally
 
 ```sh

pyproject.toml

@@ -10,8 +10,9 @@ dependencies = [
     "kernels>=0.11.1",
     "modal>=1.2.5.dev0",
     "openai-harmony>=0.0.8",
+    "python-dotenv>=1.2.1",
     "spaces>=0.42.1",
-    "torch==2.8.0",  # ZeroGPU
+    "torch==2.8.0", # ZeroGPU
     "transformers>=4.57.1",
 ]
 

src/unpredictable_lord/chat.py

@@ -5,12 +5,16 @@ Provides chat functionality by calling the LLM endpoint on Modal or using ZeroGP
 """
 
 import logging
+import os
 
 import openai_harmony as oh
+from dotenv import load_dotenv
+
+load_dotenv()
 
 logger = logging.getLogger(__name__)
 
-USE_MODAL = False
+USE_MODAL = os.getenv("USE_MODAL", "false").lower() == "true"
 
 
 if USE_MODAL:

uv.lock

@@ -1038,6 +1038,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload_time = "2024-03-01T18:36:18.57Z" },
 ]
 
+[[package]]
+name = "python-dotenv"
+version = "1.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f0/26/19cadc79a718c5edbec86fd4919a6b6d3f681039a2f6d66d14be94e75fb9/python_dotenv-1.2.1.tar.gz", hash = "sha256:42667e897e16ab0d66954af0e60a9caa94f0fd4ecf3aaf6d2d260eec1aa36ad6", size = 44221, upload_time = "2025-10-26T15:12:10.434Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/14/1b/a298b06749107c305e1fe0f814c6c74aea7b2f1e10989cb30f544a1b3253/python_dotenv-1.2.1-py3-none-any.whl", hash = "sha256:b81ee9561e9ca4004139c6cbba3a238c32b03e4894671e181b671e8cb8425d61", size = 21230, upload_time = "2025-10-26T15:12:09.109Z" },
+]
+
 [[package]]
 name = "python-multipart"
 version = "0.0.20"
@@ -1491,6 +1500,7 @@ dependencies = [
     { name = "kernels" },
     { name = "modal" },
     { name = "openai-harmony" },
+    { name = "python-dotenv" },
     { name = "spaces" },
     { name = "torch" },
     { name = "transformers" },
@@ -1508,6 +1518,7 @@ requires-dist = [
     { name = "kernels", specifier = ">=0.11.1" },
     { name = "modal", specifier = ">=1.2.5.dev0" },
     { name = "openai-harmony", specifier = ">=0.0.8" },
+    { name = "python-dotenv", specifier = ">=1.2.1" },
     { name = "spaces", specifier = ">=0.42.1" },
     { name = "torch", specifier = "==2.8.0" },
     { name = "transformers", specifier = ">=4.57.1" },