Enhance README and implement local/cloud mode support in the geography game

.gitignore

@@ -0,0 +1 @@
+.env

README.md

@@ -14,4 +14,57 @@ license: apache-2.0
 short_description: Learning Country Names, locations, flags, principal location
 ---
 
-An example chatbot using [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+# World Geography Game 🌍
+
+An interactive geography game where you try to guess the country I'm thinking of using 20 yes/no questions.
+
+Built with [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+
+## Features
+
+- 🎯 20 Questions gameplay format
+- 🌍 Covers countries from around the world
+- 🤖 AI-powered responses using Llama models
+- 🏠 Local model support for development
+- ☁️ Cloud deployment with HuggingFace OAuth
+
+## Running Locally
+
+To run this application with a local inference server (like LM Studio, Ollama, etc.):
+
+1. **Create a `.env` file** from the sample:
+   ```bash
+   cp sample.env .env
+   ```
+
+2. **Configure your local model settings** in `.env`:
+   ```env
+   MODEL_NAME=llama-3.2-3b-instruct
+   BASE_URL=http://127.0.0.1:1234/v1
+   TOKEN=abc123
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Run the application**:
+   ```bash
+   python app.py
+   ```
+
+When running locally, the app will automatically detect the environment variables and use your local model instead of requiring HuggingFace OAuth login.
+
+## Cloud Deployment
+
+When deployed to HuggingFace Spaces or running without local environment variables, the app will use HuggingFace's Inference API and require users to log in with their HuggingFace account.
+
+## How to Play
+
+1. Think of questions that can be answered with "Yes" or "No"
+2. Try to narrow down the location, language, geography, or other characteristics
+3. You have 20 questions to guess the correct country
+4. The AI will keep track of your question count and let you know when you've won or used all your questions
+
+Good luck! 🎮

app.py

@@ -2,6 +2,17 @@ import gradio as gr
 from huggingface_hub import InferenceClient
 import re
 import random
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file if it exists
+load_dotenv()
+
+# Check if we're running locally with custom model settings
+BASE_URL = os.getenv('BASE_URL')
+LOCAL_TOKEN = os.getenv('TOKEN')
+LOCAL_MODE = bool(BASE_URL and LOCAL_TOKEN)
+MODEL_NAME = os.getenv('MODEL_NAME', 'meta-llama/Llama-3.2-3B-Instruct')
 
 
 # List of countries for the game
@@ -69,90 +80,117 @@ def respond(
     max_tokens,
     temperature,
     top_p,
-    hf_token: gr.OAuthToken,
+    hf_token: gr.OAuthToken | None = None,
 ):
     """
     For more information on `huggingface_hub` Inference API support, please check the docs: https://huggingface.co/docs/huggingface_hub/v0.22.2/en/guides/inference
     """
-    # Check if user is logged in
-    if not hf_token or not hf_token.token:
-        yield "Please log in with your HuggingFace account to play the geography game!"
-        return
-    
-    client = InferenceClient(token=hf_token.token, model="meta-llama/Llama-3.2-3B-Instruct")
-
     # Generate a new system message with random country for new conversations
     if not history:
         system_message = get_system_message_with_country()
 
     messages = [{"role": "system", "content": system_message}]
-
     messages.extend(history)
-
     messages.append({"role": "user", "content": message})
 
+    # Choose client based on whether we're running locally or in the cloud
+    if LOCAL_MODE:
+        # Running locally with custom model settings
+        try:
+            # Use local inference server
+            client = InferenceClient(model=BASE_URL, token=LOCAL_TOKEN)
+        except Exception as e:
+            return f"Error connecting to local model: {str(e)}"
+    else:
+        # Running in cloud mode with HuggingFace
+        if not hf_token or not hf_token.token:
+            return "Please log in with your HuggingFace account to play the geography game!"
+        
+        client = InferenceClient(token=hf_token.token, model=MODEL_NAME)
+
     response = ""
 
-    for message in client.chat_completion(
-        messages,
-        max_tokens=max_tokens,
-        stream=True,
-        temperature=temperature,
-        top_p=top_p,
-    ):
-        choices = message.choices
-        token = ""
-        if len(choices) and choices[0].delta.content:
-            token = choices[0].delta.content
-
-        response += token
-        
+    try:
+        for message_chunk in client.chat_completion(
+            messages,
+            model=MODEL_NAME,
+            max_tokens=max_tokens,
+            stream=True,
+            temperature=temperature,
+            top_p=top_p,
+        ):
+            choices = message_chunk.choices
+            token = ""
+            if len(choices) and choices[0].delta.content:
+                token = choices[0].delta.content
+
+            response += token
+
         # Check if this is a game end response and format it nicely
         if "<<" in response and ">>" in response:
-            formatted_response = format_game_result(response)
-            yield formatted_response
+            return format_game_result(response)
         else:
-            yield response
+            return response
+    except Exception as e:
+        return f"Error during inference: {str(e)}"
 
 
 """
 For information on how to customize the ChatInterface, peruse the gradio docs: https://www.gradio.app/docs/chatinterface
 """
+
+# Create description based on mode
+if LOCAL_MODE:
+    description = f"🏠 Running locally with {MODEL_NAME}. I am thinking of a country, you have 20 yes or no questions to ask me to help you figure out what the country is"
+else:
+    description = "I am thinking of a country, you have 20 yes or no questions to ask me to help you figure out what the country is"
+
+# Common examples and settings
+examples = [
+    ["Is the country located in Europe?"],
+    ["Is it in the Northern Hemisphere?"],
+    ["Is the official language Spanish?"],
+    ["Is the capital city Rome?"],
+    ["Is this country bordered by an ocean?"],
+    ["Does this country have more than 100 million people?"],
+    ["Is this country known for producing coffee?"],
+    ["Was this country ever a colony of the United Kingdom?"],
+    ["Is this country located on an island?"],
+    ["Is the currency the Euro?"],
+]
+
+additional_inputs = [
+    gr.Textbox(visible=False, value="Geography game placeholder - will be replaced with random country", label="System message"),
+    gr.Slider(visible=False, minimum=1, maximum=2048, value=512, step=1, label="Max new tokens"),
+    gr.Slider(visible=False, minimum=0.1, maximum=4.0, value=0.7, step=0.1, label="Temperature"),
+    gr.Slider(
+        visible=False,
+        minimum=0.1,
+        maximum=1.0,
+        value=0.95,
+        step=0.05,
+        label="Top-p (nucleus sampling)",
+    ),
+]
+
+# Create wrapper function for local mode that doesn't expect OAuth token
+def respond_local(message, history, system_message, max_tokens, temperature, top_p):
+    return respond(message, history, system_message, max_tokens, temperature, top_p, None)
+
 chatbot = gr.ChatInterface(
-    respond,
+    (respond_local if LOCAL_MODE else respond),
     type="messages",
-    description="I am thinking of a country, you have 20 yes or no questions to ask me to help you figure out what the country is",
-    examples=[
-        ["Is the country located in Europe?"],
-        ["Is it in the Northern Hemisphere?"],
-        ["Is the official language Spanish?"],
-        ["Is the capital city Rome?"],
-        ["Is this country bordered by an ocean?"],
-        ["Does this country have more than 100 million people?"],
-        ["Is this country known for producing coffee?"],
-        ["Was this country ever a colony of the United Kingdom?"],
-        ["Is this country located on an island?"],
-        ["Is the currency the Euro?"],
-    ],
-    cache_examples=False,  # Disable caching to prevent login errors during deployment
-    additional_inputs=[
-        gr.Textbox(visible=False, value="Geography game placeholder - will be replaced with random country", label="System message"),
-        gr.Slider(visible=False, minimum=1, maximum=2048, value=512, step=1, label="Max new tokens"),
-        gr.Slider(visible=False, minimum=0.1, maximum=4.0, value=0.7, step=0.1, label="Temperature"),
-        gr.Slider(
-            visible=False,
-            minimum=0.1,
-            maximum=1.0,
-            value=0.95,
-            step=0.05,
-            label="Top-p (nucleus sampling)",
-        ),
-    ],
+    description=description,
+    examples=examples,
+    cache_examples=False,
+    additional_inputs=additional_inputs,
 )
 
 with gr.Blocks() as demo:
-    with gr.Sidebar():
-        gr.LoginButton()
+    if not LOCAL_MODE:
+        # Only show login button when running in cloud mode
+        with gr.Sidebar():
+            gr.LoginButton()
     chatbot.render()
 
 

requirements.txt

@@ -1,2 +1,3 @@
 gradio
-gradio[oauth]
+gradio[oauth]
+python-dotenv

sample.env

@@ -0,0 +1,3 @@
+MODEL_NAME=llama-3.2-3b-instruct
+BASE_URL=http://127.0.0.1:1234/v1
+TOKEN=abc123