Deploy Myco from CI

README.md

@@ -43,16 +43,27 @@ Design decisions should prioritize:
 - Game logic: `game/`
 - Mushroom model: `models/`
 - Mushroom catalog: `data/mushrooms.json`
+- Regression tests: `tests/test_myco_core.py`
 - Runtime dependency: `requirements.txt`
 
+## Hugging Face AI companion
+
+Myco uses the Hugging Face Inference API for both first-discovery reactions and chat replies when a token is configured in the Space. Add these Space variables/secrets:
+
+- `HF_TOKEN=<your Hugging Face access token>`
+- Optional: `MYCO_HF_MODEL_ID=meta-llama/Llama-3.1-8B-Instruct`
+
+The default model is set in code as `DEFAULT_HF_MODEL_ID = "meta-llama/Llama-3.1-8B-Instruct"`. The app still has a local safety fallback for development and outage protection: if the token is missing or the selected model errors, Myco answers with the built-in cautious companion response instead of crashing.
+
 ## Local development
 
 ```bash
 pip install -r requirements.txt
+python -m unittest discover -v
 python app.py
 ```
 
-Then open the local Gradio URL printed in the terminal.
+Run tests before launching, then open the local Gradio URL printed in the terminal.
 
 ## Hugging Face Space
 
@@ -66,3 +77,8 @@ No GitHub Actions deployment workflow is required. To deploy manually:
 4. The Space should install `gradio==6.16.0` from `requirements.txt` and start from `app.py`.
 
 The required runtime files are `README.md`, `app.py`, `requirements.txt`, `data/`, `game/`, `models/`, and `ui/`.
+
+
+## Optional deploy helper
+
+`scripts/deploy_space.py` is optional. It skips safely when `HF_BUILD_SMALL_HACKATHON_TOKEN` is not configured, and uploads to `byte-vortex/Myco` only when that token is present.

app.py

@@ -4,6 +4,7 @@ import os
 
 os.environ.setdefault("GRADIO_SSR_MODE", "False")
 
+from gradio.themes import Soft
 import gradio as gr
 
 from ui.gradio_app import build_app
@@ -14,6 +15,7 @@ demo = build_app()
 
 if __name__ == "__main__":
     demo.launch(
+        theme=Soft(primary_hue="green", secondary_hue="emerald"),
         theme=gr.themes.Soft(primary_hue="green", secondary_hue="emerald"),
         css=APP_CSS,
         ssr_mode=False,

game/catalog.py

@@ -14,4 +14,3 @@ def load_mushrooms() -> tuple[Mushroom, ...]:
     """Load the in-repo mushroom catalog."""
     raw_mushrooms = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
     return tuple(Mushroom.from_dict(item) for item in raw_mushrooms)
-    

game/engine.py

@@ -95,6 +95,13 @@ def _hf_companion_answer(message, current):
             max_tokens=90,
             temperature=0.8,
         )
+        content = response.choices[0].message.content or ""
+        answer = content.strip()
+    except (AttributeError, IndexError, TypeError, ValueError):
+        return None
+    except Exception:
+        return None
+
     except Exception:
         return None
 
@@ -118,6 +125,7 @@ def hf_companion_status():
 def _hf_token():
     """Return the first configured Hugging Face token without exposing it."""
     for env_name in HF_TOKEN_ENV_VARS:
+        token = os.getenv(env_name, "").strip()
         token = os.getenv(env_name)
         if token:
             return token
@@ -138,7 +146,7 @@ def _hf_messages(message, current):
             f"Lore: {mushroom.lore}"
         )
 
-    return (
+    return [
         {
             "role": "system",
             "content": (
@@ -151,7 +159,7 @@ def _hf_messages(message, current):
             "role": "user",
             "content": f"{mushroom_context} Player asks: {message}",
         },
-    )
+    ]
 
 
 companion_reply = myco_reply

game/state.py

@@ -22,4 +22,4 @@ def mushroom_from_state(current: MushroomState) -> Mushroom:
 
 def collection_contains(collection: CollectionState, mushroom_name: str) -> bool:
     """Return whether the MycoDex already has a mushroom by name."""
-    return any(entry["name"] == mushroom_name for entry in collection)
+    return any(entry.get("name") == mushroom_name for entry in collection)

scripts/deploy_space.py

@@ -25,7 +25,7 @@ models/**/*.safetensors
 
 def get_ignore_patterns():
     """Return upload ignore patterns as a list for huggingface_hub."""
-    return IGNORE_PATTERNS_TEXT.split()
+    return [str(pattern) for pattern in IGNORE_PATTERNS_TEXT.split()]
 
 
 def get_hf_token():

tests/test_myco_core.py

@@ -161,6 +161,27 @@ class MycoCoreTests(unittest.TestCase):
         self.assertIn(current["name"], updated_history[-1]["content"])
         self.assertIn("unknown", updated_history[-1]["content"].lower())
 
+    def test_companion_api_falls_back_on_malformed_response(self):
+        _mushroom, current, history = discover_mushroom([])
+
+        def broken_client(token):
+            return SimpleNamespace(
+                token=token,
+                chat_completion=lambda **kwargs: SimpleNamespace(choices=()),
+            )
+
+        api_env = {
+            "HF_TOKEN": " fake-token ",
+            "HF_API_TOKEN": "",
+            "HF_BUILD_SMALL_HACKATHON_TOKEN": "",
+        }
+        with patch.dict(os.environ, api_env, clear=False):
+            with patch("game.engine.InferenceClient", broken_client):
+                prompt, updated_history = companion_reply("What is this?", history, current)
+
+        self.assertEqual(prompt, "")
+        self.assertIn(current["name"], updated_history[-1]["content"])
+
     def test_collect_current_prevents_duplicates(self):
         _mushroom, current, history = discover_mushroom([])
         collection, history = collect_current(current, [], history)
@@ -173,6 +194,8 @@ class MycoCoreTests(unittest.TestCase):
     def test_study_and_eat_are_safe(self):
         _mushroom, current, history = discover_mushroom([])
         studied, study_history = study_current(current, history)
+        self.assertIsNotNone(studied)
+        assert studied is not None
         eat_history = eat_current(studied, study_history)
 
         self.assertEqual(studied["studied"], "Yes")

ui/gradio_app.py

@@ -1,5 +1,7 @@
 """Gradio app composition for Myco."""
 
+from typing import Any, cast
+
 import gradio as gr
 
 from game.engine import (
@@ -22,7 +24,7 @@ from ui.renderers import (
     world_map_markdown,
 )
 
-EMPTY_COLLECTION = tuple()
+EMPTY_COLLECTION = None
 
 HOME_MARKDOWN = """
 ## Welcome to the Myco forest
@@ -106,7 +108,7 @@ def build_app():
     """Build the Gradio interface for Hugging Face Spaces."""
     with gr.Blocks(title="Myco") as demo:
         current_mushroom = gr.State(None)
-        collection = gr.State(EMPTY_COLLECTION)
+        collection = gr.State([])
         gr.HTML(hero_markdown())
 
         with gr.Tabs():
@@ -133,7 +135,7 @@ def build_app():
                             study_button = gr.Button("Study")
                     with gr.Column(scale=3):
                         chat = gr.Chatbot(
-                            value=welcome_history(),
+                            value=cast(Any, welcome_history()),
                             label="Myco Chat",
                             height=360,
                         )

ui/renderers.py

@@ -110,8 +110,6 @@ def mushroom_card(mushroom: Mushroom | None) -> str:
     )
 
 
-
-
 def world_map_markdown(collection: CollectionState | None) -> str:
     """Render a game-like world map with unlocks and achievements."""
     count = len(_safe_collection(collection))
@@ -161,6 +159,7 @@ def _achievement_badge(label: str, unlocked: bool) -> str:
     icon = "🏅" if unlocked else "◇"
     return f'<span class="achievement {state}">{icon} {escape(label)}</span>'
 
+
 def dex_markdown(collection: CollectionState | None) -> str:
     """Render collected mushrooms as a compact MycoDex."""
     current_collection = _safe_collection(collection)