Clean repository root for HF Spaces

.gitignore

@@ -0,0 +1,30 @@
+# ── Python ────────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/
+*.egg-info/
+dist/
+build/
+
+# ── Node / Vite ───────────────────────────────────────────────────────────────
+ui/node_modules/
+ui/.vite/
+ui/dist/
+
+# ── Environment secrets — NEVER commit these ─────────────────────────────────
+.env
+.env.local
+.env.*.local
+ui/.env
+ui/.env.local
+ui/.env.*.local
+
+# ── OS / Editor ───────────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp

Dockerfile

@@ -0,0 +1,68 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 1 – Build the Vite / React frontend
+# ─────────────────────────────────────────────────────────────────────────────
+FROM node:20-slim AS frontend-builder
+
+WORKDIR /app/ui
+
+# Install deps first (better layer caching)
+COPY ui/package.json ui/package-lock.json* ./
+RUN npm ci --prefer-offline
+
+# Copy all UI source
+COPY ui/ ./
+
+# Vite bakes VITE_* vars into the static bundle at build time.
+# HF Spaces forwards the matching secrets as Docker build-args automatically
+# when you set them in Space Settings → Variables and secrets.
+ARG VITE_HF_TOKEN=""
+ARG VITE_HF_MODEL="mistralai/Mistral-7B-Instruct-v0.2"
+ENV VITE_HF_TOKEN=${VITE_HF_TOKEN}
+ENV VITE_HF_MODEL=${VITE_HF_MODEL}
+
+RUN npm run build
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 2 – Python backend + Nginx to serve frontend
+# ─────────────────────────────────────────────────────────────────────────────
+FROM python:3.11-slim
+
+# System packages: nginx for static serving + reverse-proxy
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    nginx \
+    curl \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Application source
+COPY models.py .
+COPY inference.py .
+COPY server/ ./server/
+COPY openenv.yaml .
+
+# Nginx configuration
+COPY nginx.conf /etc/nginx/nginx.conf
+
+# Built frontend from stage 1
+COPY --from=frontend-builder /app/ui/dist ./ui/dist
+
+# Startup script
+COPY start.sh /start.sh
+RUN chmod +x /start.sh
+
+# HF Spaces exposes port 7860
+EXPOSE 7860
+
+# Runtime environment (overridden by HF Space secrets at runtime)
+ENV PORT=7860 \
+    HF_MODEL="mistralai/Mistral-7B-Instruct-v0.2" \
+    HF_TOKEN="" \
+    PYTHONUNBUFFERED=1
+
+CMD ["/start.sh"]

inference.py

@@ -0,0 +1,280 @@
+"""
+inference.py
+─────────────────────────────────────────────────────────────────────────────
+OpenEnv-compliant inference environment for Survival Island.
+Provides step(), reset(), state() methods and task graders.
+
+Uses OpenAI client format with [START], [STEP], [END] logging.
+"""
+
+import json
+import logging
+import os
+from typing import Any, Dict, Optional, Tuple
+
+from openai import OpenAI
+
+# ── Logging setup ─────────────────────────────────────────────────────────────
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# ── OpenEnv Environment ───────────────────────────────────────────────────────
+
+class SurvivalIslandEnvironment:
+    """
+    OpenEnv-compliant environment wrapper for Survival Island.
+    Provides the required step(), reset(), state() interface.
+    """
+
+    def __init__(self):
+        """Initialize the environment."""
+        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY", ""))
+        self.generation = 0
+        self.total_resources_collected = 0
+        self.challenges_won = 0
+        self.current_state = self._create_initial_state()
+        
+        logger.info("[START] Survival Island environment initialized")
+
+    def _create_initial_state(self) -> Dict[str, Any]:
+        """Create initial game state."""
+        return {
+            "generation": 0,
+            "health": 100.0,
+            "hunger": 50.0,
+            "thirst": 50.0,
+            "stamina": 100.0,
+            "fear": 0.0,
+            "wood": 0,
+            "stone": 0,
+            "food": 0,
+            "water": 0,
+            "playerX": 1000.0,
+            "isNight": False,
+            "inventory": {
+                "spear": False,
+                "bow": False,
+                "fishingRod": False,
+                "boat": False,
+            },
+            "baseCamp": {
+                "x": None,
+                "y": None,
+                "level": 0,
+            },
+            "memory": {
+                "evolutionLevel": 1,
+                "pastDeaths": [],
+                "totalGenerations": 0,
+                "challengesWon": 0,
+            },
+            "activeChallenge": None,
+        }
+
+    def reset(self) -> Dict[str, Any]:
+        """Reset the environment to initial state."""
+        logger.info("[STEP] reset() called")
+        self.generation = 0
+        self.total_resources_collected = 0
+        self.challenges_won = 0
+        self.current_state = self._create_initial_state()
+        logger.info("[END] Environment reset complete")
+        return self.current_state
+
+    def step(self, action: str) -> Tuple[Dict[str, Any], float, bool, Dict[str, Any]]:
+        """
+        Execute one step in the environment.
+        
+        Args:
+            action: Action taken by the agent (e.g., "FORAGE", "HUNT", "FISH")
+        
+        Returns:
+            Tuple of (state, reward, done, info)
+        """
+        logger.info(f"[STEP] Action: {action}")
+        
+        # Simulate action effects
+        reward = 0.0
+        done = False
+        info = {}
+
+        action_upper = action.upper().strip()
+
+        # Resource gathering actions
+        if action_upper == "FORAGE":
+            self.current_state["food"] += 5
+            self.total_resources_collected += 5
+            reward = 0.1
+        elif action_upper == "FISH":
+            self.current_state["food"] += 8
+            self.total_resources_collected += 8
+            reward = 0.15
+        elif action_upper == "GET_WATER":
+            self.current_state["water"] += 10
+            self.total_resources_collected += 10
+            reward = 0.15
+        elif action_upper == "HUNT":
+            self.current_state["food"] += 20
+            self.total_resources_collected += 20
+            reward = 0.25
+        elif action_upper in ["CRAFT_SPEAR", "CRAFT_BOW", "CRAFT_ROD", "CRAFT_BOAT"]:
+            # Crafting actions grant survival tools
+            tool_key = action_upper.lower().replace("craft_", "").replace("_", "")
+            if tool_key in self.current_state["inventory"]:
+                self.current_state["inventory"][tool_key] = True
+            reward = 0.2
+        elif action_upper == "BUILD_CAMP":
+            if self.current_state["baseCamp"]["level"] == 0:
+                self.current_state["baseCamp"]["x"] = self.current_state["playerX"]
+                self.current_state["baseCamp"]["level"] = 1
+            reward = 0.3
+        elif action_upper == "UPGRADE_CAMP":
+            self.current_state["baseCamp"]["level"] = min(
+                self.current_state["baseCamp"]["level"] + 1, 3
+            )
+            reward = 0.25
+        elif action_upper == "FLEE":
+            reward = 0.1
+        elif action_upper == "WANDER":
+            reward = -0.05
+
+        # Decay resources each step
+        self.current_state["hunger"] = max(0, self.current_state["hunger"] - 2)
+        self.current_state["thirst"] = max(0, self.current_state["thirst"] - 1.5)
+        self.current_state["stamina"] = max(0, self.current_state["stamina"] - 1)
+
+        # Consume resources if available
+        if self.current_state["food"] > 0:
+            self.current_state["hunger"] = min(100, self.current_state["hunger"] + 3)
+            self.current_state["food"] -= 1
+
+        if self.current_state["water"] > 0:
+            self.current_state["thirst"] = min(100, self.current_state["thirst"] + 2)
+            self.current_state["water"] -= 1
+
+        # Check death conditions
+        if self.current_state["health"] <= 0:
+            done = True
+            info["death_reason"] = "health_depleted"
+            reward = -1.0
+        elif self.current_state["hunger"] <= 0:
+            self.current_state["health"] -= 10
+            reward -= 0.2
+        elif self.current_state["thirst"] <= 0:
+            self.current_state["health"] -= 15
+            reward -= 0.3
+
+        self.generation += 1
+        self.current_state["generation"] = self.generation
+        self.current_state["memory"]["totalGenerations"] = self.generation
+
+        logger.info(f"[END] Step {self.generation}: reward={reward:.3f}, done={done}")
+        return self.current_state, reward, done, info
+
+    def state(self) -> Dict[str, Any]:
+        """Get current environment state."""
+        logger.info("[STEP] state() called")
+        logger.info("[END] State retrieved")
+        return self.current_state
+
+
+# ── Task Graders (0.0 to 1.0) ────────────────────────────────────────────────
+
+class TaskGraders:
+    """Graders for the 3 required tasks."""
+
+    @staticmethod
+    def grade_survival_expert(state: Dict[str, Any]) -> float:
+        """
+        Task 1 (Easy): Survive for 50+ generations.
+        Grader: Returns (min(generations, 50) / 50)
+        """
+        generations = state.get("generation", 0)
+        score = min(generations, 50) / 50.0
+        return min(score, 1.0)
+
+    @staticmethod
+    def grade_resourceful_gatherer(state: Dict[str, Any]) -> float:
+        """
+        Task 2 (Medium): Collect 500+ total resources.
+        Grader: Returns (min(total_resources, 500) / 500)
+        """
+        # Simulating total resources by checking inventory state
+        memory = state.get("memory", {})
+        total_resources = memory.get("challengesWon", 0) * 100  # Proxy metric
+        # Add actual collected resources
+        total_resources += (
+            state.get("wood", 0)
+            + state.get("stone", 0)
+            + (state.get("food", 0) * 2)
+            + (state.get("water", 0) * 2)
+        )
+        score = min(total_resources, 500) / 500.0
+        return min(score, 1.0)
+
+    @staticmethod
+    def grade_challenge_master(state: Dict[str, Any]) -> float:
+        """
+        Task 3 (Hard): Win 10+ challenges and reach evolution level 5.
+        Grader: Returns (min(challenges_won, 10) / 10) * (evolution_level / 5)
+        """
+        memory = state.get("memory", {})
+        challenges_won = memory.get("challengesWon", 0)
+        evolution_level = memory.get("evolutionLevel", 1)
+
+        challenge_score = min(challenges_won, 10) / 10.0
+        evolution_score = min(evolution_level, 5) / 5.0
+        score = (challenge_score + evolution_score) / 2.0
+        return min(score, 1.0)
+
+
+# ── Main Entry Point ──────────────────────────────────────────────────────────
+
+def main():
+    """Demonstrate environment usage."""
+    logger.info("[START] Initialization")
+    
+    env = SurvivalIslandEnvironment()
+    graders = TaskGraders()
+
+    # Reset environment
+    state = env.reset()
+    logger.info(f"Initial state: generation={state['generation']}")
+
+    # Simulate a few steps
+    logger.info("[START] Simulation")
+    actions = ["FORAGE", "BUILD_CAMP", "CRAFT_SPEAR", "HUNT", "GET_WATER"]
+    
+    for action in actions:
+        logger.info(f"[STEP] Executing action: {action}")
+        next_state, reward, done, info = env.step(action)
+        logger.info(f"[END] Step completed: reward={reward}, done={done}")
+
+        if done:
+            logger.info(f"[END] Episode terminated: {info}")
+            break
+
+    # Grade tasks
+    final_state = env.state()
+    logger.info("[START] Task Grading")
+    
+    task1_score = graders.grade_survival_expert(final_state)
+    task2_score = graders.grade_resourceful_gatherer(final_state)
+    task3_score = graders.grade_challenge_master(final_state)
+    
+    logger.info(f"[STEP] Task 1 (Survival Expert): {task1_score:.3f}")
+    logger.info(f"[STEP] Task 2 (Resourceful Gatherer): {task2_score:.3f}")
+    logger.info(f"[STEP] Task 3 (Challenge Master): {task3_score:.3f}")
+    
+    logger.info("[END] All tasks graded")
+
+    print("\n--- Results ---")
+    print(f"Task 1 Score: {task1_score:.3f}")
+    print(f"Task 2 Score: {task2_score:.3f}")
+    print(f"Task 3 Score: {task3_score:.3f}")
+    print(f"Average Score: {(task1_score + task2_score + task3_score) / 3:.3f}")
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,179 @@
+"""
+models.py
+─────────────────────────────────────────────────────────────────────────────
+Handles LLM inference for the Survival Island AI agent.
+
+Priority chain
+--------------
+1. Local transformers pipeline   (available on GPU Spaces – uncomment deps)
+2. HuggingFace Inference API     (works on CPU Spaces, needs HF_TOKEN)
+3. Rule-based fallback           (no network / no token)
+
+Environment variables
+---------------------
+HF_TOKEN   – HuggingFace API token (required for path 2)
+HF_MODEL   – Model repo ID, e.g. "mistralai/Mistral-7B-Instruct-v0.2"
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import threading
+from typing import Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# ── Config ────────────────────────────────────────────────────────────────────
+HF_TOKEN: str = os.getenv("HF_TOKEN", "")
+HF_MODEL: str = os.getenv("HF_MODEL", "mistralai/Mistral-7B-Instruct-v0.2")
+
+VALID_ACTIONS: set[str] = {
+    "FORAGE", "HUNT", "FISH", "GET_WATER", "SEEK_SHELTER",
+    "BUILD_CAMP", "UPGRADE_CAMP", "CRAFT_SPEAR", "CRAFT_BOW",
+    "CRAFT_ROD", "CRAFT_BOAT", "EVACUATE", "FIGHT", "FLEE", "WANDER",
+}
+
+# ── Singleton ─────────────────────────────────────────────────────────────────
+_lock = threading.Lock()
+_pipeline = None          # transformers Pipeline object (optional)
+_use_local: bool = False  # True once local pipeline loaded successfully
+
+
+# ── Local pipeline (optional – GPU Spaces) ────────────────────────────────────
+def _try_load_local() -> bool:
+    """
+    Attempts to load the model locally with transformers + torch.
+    Returns True on success. Skipped silently on CPU-only environments.
+    Uncomment torch/transformers in requirements.txt to enable this path.
+    """
+    global _pipeline, _use_local
+    try:
+        import torch
+        from transformers import pipeline as hf_pipeline  # type: ignore
+
+        logger.info(f"[models] Loading {HF_MODEL} locally …")
+        device = 0 if torch.cuda.is_available() else -1
+        _pipeline = hf_pipeline(
+            "text-generation",
+            model=HF_MODEL,
+            token=HF_TOKEN or None,
+            device=device,
+            torch_dtype=torch.float16 if device >= 0 else torch.float32,
+            max_new_tokens=80,
+        )
+        _use_local = True
+        logger.info(f"[models] Local pipeline ready (device={device})")
+        return True
+    except Exception as exc:
+        logger.warning(f"[models] Local pipeline skipped: {exc}")
+        return False
+
+
+def get_pipeline():
+    """Return the pipeline, initialising on first call."""
+    with _lock:
+        if _pipeline is None:
+            _try_load_local()
+    return _pipeline
+
+
+# ── Output parser ─────────────────────────────────────────────────────────────
+def _parse_action(raw: str) -> dict:
+    """
+    Extract {"action": ..., "thought": ...} from model output.
+    Handles markdown fences, leading prose, trailing noise.
+    """
+    # Strip markdown fences
+    cleaned = re.sub(r"```(?:json)?|```", "", raw, flags=re.IGNORECASE)
+    # Keep only the first JSON object
+    match = re.search(r"\{[^}]+\}", cleaned, re.DOTALL)
+    if not match:
+        raise ValueError(f"No JSON object in model output: {raw!r}")
+    obj = json.loads(match.group())
+    action = str(obj.get("action", "WANDER")).upper()
+    if action not in VALID_ACTIONS:
+        logger.warning(f"[models] Unknown action '{action}', defaulting to WANDER")
+        action = "WANDER"
+    return {
+        "action": action,
+        "thought": str(obj.get("thought", "Processing…")),
+    }
+
+
+# ── Inference paths ───────────────────────────────────────────────────────────
+def infer_local(prompt: str) -> dict:
+    """Run generation using the locally loaded transformers pipeline."""
+    pipe = get_pipeline()
+    if pipe is None:
+        raise RuntimeError("Local pipeline not available")
+    outputs = pipe(
+        prompt,
+        max_new_tokens=80,
+        temperature=0.7,
+        do_sample=True,
+        return_full_text=False,
+    )
+    return _parse_action(outputs[0]["generated_text"])
+
+
+def infer_api(prompt: str) -> dict:
+    """Call the HuggingFace Inference API (remote, no GPU needed)."""
+    if not HF_TOKEN:
+        raise RuntimeError("HF_TOKEN not set – cannot call Inference API")
+    url = f"https://api-inference.huggingface.co/models/{HF_MODEL}"
+    resp = requests.post(
+        url,
+        headers={
+            "Authorization": f"Bearer {HF_TOKEN}",
+            "Content-Type": "application/json",
+        },
+        json={
+            "inputs": prompt,
+            "parameters": {
+                "max_new_tokens": 80,
+                "temperature": 0.7,
+                "return_full_text": False,
+                "stop": ["\n\n", "</s>", "[INST]"],
+            },
+        },
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    raw = (
+        data[0]["generated_text"]
+        if isinstance(data, list)
+        else data.get("generated_text", "")
+    )
+    return _parse_action(raw)
+
+
+def run_inference(prompt: str) -> dict:
+    """
+    Main entry point used by server/app.py.
+
+    Tries local → API → rule-based fallback in that order.
+    Never raises – always returns a valid {"action", "thought"} dict.
+    """
+    # 1. Local transformers pipeline (GPU Space)
+    if _use_local:
+        try:
+            return infer_local(prompt)
+        except Exception as exc:
+            logger.warning(f"[models] Local inference failed: {exc}")
+
+    # 2. HuggingFace Inference API (CPU Space)
+    if HF_TOKEN:
+        try:
+            return infer_api(prompt)
+        except Exception as exc:
+            logger.warning(f"[models] Inference API failed: {exc}")
+
+    # 3. Hard fallback
+    logger.error("[models] All inference paths failed – returning WANDER")
+    return {"action": "WANDER", "thought": "Inference offline. Wandering."}

nginx.conf

@@ -0,0 +1,57 @@
+worker_processes 1;
+error_log /dev/stderr warn;
+pid /tmp/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+    access_log    /dev/stdout;
+    sendfile      on;
+    tcp_nopush    on;
+    keepalive_timeout 65;
+
+    gzip on;
+    gzip_types
+        text/plain
+        text/css
+        text/javascript
+        application/javascript
+        application/json
+        application/wasm
+        image/svg+xml;
+
+    server {
+        listen 7860;
+        server_name _;
+
+        root /app/ui/dist;
+        index index.html;
+
+        # ── React SPA: always return index.html for unknown paths ──────────
+        location / {
+            try_files $uri $uri/ /index.html;
+        }
+
+        # ── Proxy /api/* → FastAPI on port 8000 ───────────────────────────
+        location /api/ {
+            proxy_pass         http://127.0.0.1:8000;
+            proxy_http_version 1.1;
+            proxy_set_header   Host              $host;
+            proxy_set_header   X-Real-IP         $remote_addr;
+            proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+            proxy_set_header   X-Forwarded-Proto $scheme;
+            proxy_read_timeout 60s;
+            proxy_send_timeout 60s;
+        }
+
+        # ── Static asset caching ───────────────────────────────────────────
+        location ~* \.(js|css|wasm|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+    }
+}

openenv.yaml

@@ -0,0 +1,84 @@
+name: Survival_Island
+version: "1.0.0"
+description: >
+  An AI-powered 2-D survival simulation where a HuggingFace LLM agent
+  autonomously makes survival decisions across a procedurally-generated
+  6000 × 3000 world. Built for the Meta PyTorch Hackathon.
+
+# ── Hugging Face Space ────────────────────────────────────────────────────────
+space:
+  repo_id: suraj291/Survival_Island   # change to your HF username/repo
+  sdk: docker
+  hardware: cpu-basic                  # upgrade to gpu-t4-small for local inference
+  title: "Survival Island – LLM Survival Agent"
+  emoji: 🏝️
+  colorFrom: green
+  colorTo: blue
+  pinned: false
+
+# ── Secrets / Variables  (set in HF Space → Settings → Variables and secrets)
+env:
+  secrets:
+    - name: HF_TOKEN
+      description: >
+        HuggingFace API token (read scope is enough for Inference API).
+        Also baked into the Vite bundle as VITE_HF_TOKEN at build time.
+
+  variables:
+    - name: HF_MODEL
+      default: "mistralai/Mistral-7B-Instruct-v0.2"
+      description: >
+        Any HF chat/instruct model compatible with the [INST] prompt format.
+        Alternatives: HuggingFaceH4/zephyr-7b-beta
+                      meta-llama/Llama-3.1-8B-Instruct (needs license accept)
+    - name: PORT
+      default: "7860"
+      description: Port exposed by the Docker container (HF Spaces default).
+
+# ── Build ─────────────────────────────────────────────────────────────────────
+build:
+  dockerfile: Dockerfile
+  context: .
+  steps:
+    - name: install_python_deps
+      run: pip install -r requirements.txt --no-cache-dir
+
+    - name: build_frontend
+      run: |
+        cd ui
+        npm ci
+        npm run build
+      env:
+        VITE_HF_TOKEN: "${HF_TOKEN}"
+        VITE_HF_MODEL: "${HF_MODEL}"
+
+# ── Runtime services ──────────────────────────────────────────────────────────
+services:
+  backend:
+    type: fastapi
+    entrypoint: "uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 1"
+    healthcheck: "/api/health"
+
+  frontend:
+    type: static
+    serve_dir: "ui/dist"
+
+# ── Model / hardware ──────────────────────────────────────────────────────────
+model:
+  framework: pytorch
+  task: text-generation
+  device: cpu          # set to cuda on gpu-* hardware tiers
+  load_in_8bit: false
+
+# ── Push ignore list ──────────────────────────────────────────────────────────
+push:
+  ignore:
+    - "ui/node_modules"
+    - "ui/.vite"
+    - "ui/dist"
+    - "__pycache__"
+    - "*.pyc"
+    - ".env"
+    - ".env.local"
+    - "ui/.env.local"
+    - ".git"

requirements.txt

@@ -0,0 +1,21 @@
+# ── Web framework ─────────────────────────────────────────────────────────────
+fastapi==0.111.0
+uvicorn[standard]==0.29.0
+pydantic==2.7.1
+
+# ── HTTP (Inference API fallback) ─────────────────────────────────────────────
+requests==2.32.3
+httpx==0.27.0
+
+# ── Utilities ─────────────────────────────────────────────────────────────────
+python-dotenv==1.0.1
+
+# ── OpenEnv inference ──────────────────────────────────────────────────────────
+openai==1.3.0
+
+# ── Optional: local model inference ──────────────────────────────────────────
+# Uncomment these if you deploy on a GPU Space (hardware: gpu-t4-small or above)
+# torch==2.3.0
+# transformers==4.41.0
+# accelerate==0.30.0
+# bitsandbytes==0.43.1   # 8-bit quantisation – halves VRAM usage

server/__init__.py

@@ -0,0 +1 @@
+# server package – FastAPI backend for Survival Island

server/app.py

@@ -0,0 +1,164 @@
+"""
+server/app.py
+─────────────────────────────────────────────────────────────────────────────
+FastAPI backend for Survival Island.
+
+Endpoints
+---------
+GET  /api/health    liveness probe (used by start.sh and HF healthcheck)
+GET  /api/config    safe public config (model name, pipeline status)
+POST /api/infer     LLM survival-action inference
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from server.environment import GameState, InferResponse, build_prompt
+import models
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)-8s] %(name)s: %(message)s",
+)
+logger = logging.getLogger("survival.api")
+
+
+# ── Lifespan (startup / shutdown) ─────────────────────────────────────────────
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Pre-warm the model pipeline in a daemon thread on startup."""
+    import threading
+
+    def _warm():
+        logger.info("Pre-warming model pipeline…")
+        models.get_pipeline()
+        logger.info("Pipeline warm-up complete.")
+
+    threading.Thread(target=_warm, daemon=True).start()
+    yield
+    logger.info("Survival Island API shutting down.")
+
+
+# ── App ───────────────────────────────────────────────────────────────────────
+app = FastAPI(
+    title="Survival Island API",
+    description=(
+        "LLM-powered survival agent backend.\n"
+        "Built for the Meta PyTorch Hackathon."
+    ),
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],          # tighten in production if needed
+    allow_methods=["GET", "POST", "OPTIONS"],
+    allow_headers=["*"],
+)
+
+
+# ── Simple in-process rate limiter ────────────────────────────────────────────
+_last_call: dict[str, float] = {}
+_MIN_INTERVAL = 4.0  # seconds between /api/infer calls per IP
+
+
+def _rate_ok(ip: str) -> bool:
+    now = time.monotonic()
+    if now - _last_call.get(ip, 0.0) < _MIN_INTERVAL:
+        return False
+    _last_call[ip] = now
+    return True
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+@app.get("/api/health")
+async def health():
+    """Liveness probe — always returns 200 while the process is running."""
+    return {
+        "status": "ok",
+        "model": os.getenv("HF_MODEL", "unset"),
+        "localPipeline": models._use_local,
+    }
+
+
+@app.get("/", include_in_schema=False)
+async def root():
+    """Root info route for browser access."""
+    return {
+        "message": "Survival Island API is running.",
+        "endpoints": ["/api/health", "/api/config", "/api/infer"],
+    }
+
+
+@app.get("/api/config")
+async def config():
+    """Public runtime configuration for the frontend."""
+    return {
+        "model": os.getenv("HF_MODEL", "mistralai/Mistral-7B-Instruct-v0.2"),
+        "hasToken": bool(os.getenv("HF_TOKEN")),
+        "localPipeline": models._use_local,
+    }
+
+
+@app.post("/api/infer", response_model=InferResponse)
+async def infer(state: GameState, request: Request):
+    """
+    Accept a GameState JSON body, build the LLM prompt,
+    run inference, and return the chosen action + thought.
+
+    Inference priority: local pipeline → HF Inference API → rule fallback.
+    """
+    ip = request.client.host if request.client else "unknown"
+    if not _rate_ok(ip):
+        raise HTTPException(
+            status_code=429,
+            detail="Too many requests — wait a few seconds.",
+        )
+
+    prompt = build_prompt(state)
+    logger.info(
+        f"[infer] gen={state.generation} ip={ip} "
+        f"challenge={state.activeChallenge.type if state.activeChallenge else 'none'}"
+    )
+
+    # Try inference paths
+    source = "fallback"
+    try:
+        if models._use_local:
+            result = models.infer_local(prompt)
+            source = "local"
+        elif os.getenv("HF_TOKEN"):
+            result = models.infer_api(prompt)
+            source = "api"
+        else:
+            result = models.run_inference(prompt)
+    except Exception as exc:
+        logger.warning(f"[infer] Primary inference failed ({exc}), using fallback.")
+        result = models.run_inference(prompt)
+
+    return InferResponse(
+        action=result["action"],
+        thought=result["thought"],
+        source=source,
+    )
+
+
+# ── Global error handler ──────────────────────────────────────────────────────
+@app.exception_handler(Exception)
+async def _global_error(request: Request, exc: Exception):
+    logger.error(f"Unhandled error on {request.url}: {exc}", exc_info=True)
+    return JSONResponse(
+        status_code=500,
+        content={"detail": "Internal server error."},
+    )

server/environment.py

@@ -0,0 +1,172 @@
+"""
+server/environment.py
+─────────────────────────────────────────────────────────────────────────────
+Pydantic v2 models that mirror the React game state sent from the frontend,
+plus the prompt builder that converts a GameState into the [INST] string
+consumed by the LLM.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+
+# ── Request / Response models ─────────────────────────────────────────────────
+
+class Inventory(BaseModel):
+    spear: bool = False
+    bow: bool = False
+    fishingRod: bool = False
+    boat: bool = False
+
+
+class BaseCamp(BaseModel):
+    x: Optional[float] = None
+    y: Optional[float] = None
+    level: int = 0
+
+
+class AIMemory(BaseModel):
+    evolutionLevel: int = 1
+    pastDeaths: List[str] = Field(default_factory=list)
+    totalGenerations: int = 0
+    challengesWon: int = 0
+
+
+class ActiveChallenge(BaseModel):
+    name: str
+    type: str
+    timeLimit: int
+    maxTime: int = 0
+    progress: str = ""
+
+
+class GameState(BaseModel):
+    """Full agent snapshot sent by the frontend to /api/infer."""
+
+    # Vitals
+    health:  float = Field(..., ge=0, le=100)
+    hunger:  float = Field(..., ge=0, le=100)
+    thirst:  float = Field(..., ge=0, le=100)
+    stamina: float = Field(..., ge=0, le=100)
+    fear:    float = Field(default=0, ge=0, le=100)
+
+    # Resources
+    wood:  int = 0
+    stone: int = 0
+    food:  int = 0
+    water: int = 0
+
+    # World context
+    playerX:      float = 1000
+    isNight:      bool  = False
+    activeEvents: List[str] = Field(default_factory=list)
+    predatorNear: bool  = False
+
+    # Agent state
+    inventory: Inventory  = Field(default_factory=Inventory)
+    baseCamp:  BaseCamp   = Field(default_factory=BaseCamp)
+    memory:    AIMemory   = Field(default_factory=AIMemory)
+    generation: int = 1
+
+    # Optional active challenge
+    activeChallenge: Optional[ActiveChallenge] = None
+
+
+class InferResponse(BaseModel):
+    action: str
+    thought: str
+    source: str   # "local" | "api" | "fallback"
+
+
+# ── Prompt construction ───────────────────────────────────────────────────────
+
+_DEATH_LESSON_MAP: dict[str, str] = {
+    "starvation":  "CRITICAL: Prioritize food — starvation has killed me before.",
+    "dehydration": "CRITICAL: Prioritize water — dehydration has killed me before.",
+    "hypothermia": "CRITICAL: Seek shelter at night — hypothermia has killed me before.",
+    "heatstroke":  "CRITICAL: Find shade/water during heatwaves — heatstroke has killed me before.",
+    "lion":        "CRITICAL: Craft a spear/bow before exploring. FLEE when predators are near until armed.",
+    "mauled":      "CRITICAL: Craft a spear/bow before exploring. FLEE when predators are near until armed.",
+    "panther":     "CRITICAL: Craft a spear/bow before exploring. FLEE when predators are near until armed.",
+    "crocodile":   "CRITICAL: Avoid water edges without a boat — crocodiles are deadly.",
+    "flood":       "CRITICAL: During floods, evacuate eastward IMMEDIATELY.",
+}
+
+VALID_ACTIONS = (
+    "FORAGE, HUNT, FISH, GET_WATER, SEEK_SHELTER, BUILD_CAMP, UPGRADE_CAMP, "
+    "CRAFT_SPEAR, CRAFT_BOW, CRAFT_ROD, CRAFT_BOAT, EVACUATE, FIGHT, FLEE, WANDER"
+)
+
+
+def _derive_lessons(past_deaths: list[str]) -> list[str]:
+    seen: set[str] = set()
+    lessons: list[str] = []
+    for death in past_deaths:
+        low = death.lower()
+        for keyword, lesson in _DEATH_LESSON_MAP.items():
+            if keyword in low and lesson not in seen:
+                seen.add(lesson)
+                lessons.append(lesson)
+    return lessons
+
+
+def _strategy_label(memory: AIMemory) -> str:
+    n = len(memory.pastDeaths)
+    if n >= 5:
+        return "veteran"
+    if n >= 3:
+        return "cautious"
+    if memory.evolutionLevel > 1:
+        return "experienced"
+    return "basic"
+
+
+def build_prompt(state: GameState) -> str:
+    """
+    Convert a GameState into the [INST] prompt consumed by the LLM.
+    Mirrors the prompt built in App.jsx so server-side inference
+    produces identical quality to client-side inference.
+    """
+    lessons = _derive_lessons(state.memory.pastDeaths)
+    strategy = _strategy_label(state.memory)
+
+    lessons_block = (
+        "\n".join(f"{i + 1}. {l}" for i, l in enumerate(lessons))
+        if lessons
+        else "No prior deaths — explore and gather resources."
+    )
+
+    challenge_block = ""
+    if state.activeChallenge:
+        c = state.activeChallenge
+        challenge_block = (
+            f'\nACTIVE CHALLENGE: "{c.name}" (type: {c.type}) — {c.timeLimit}s remaining.\n'
+            f"Challenge progress: {c.progress or 'just started'}.\n"
+            "Prioritize completing this challenge above all else!"
+        )
+
+    inv = state.inventory
+    return (
+        f"<s>[INST] You are the survival instinct AI (Generation {state.generation}) "
+        f"of Subject-01. You have died {len(state.memory.pastDeaths)} times.\n\n"
+        f"STRATEGY LEVEL: {strategy.upper()}\n"
+        f"\nLESSONS FROM PAST DEATHS:\n{lessons_block}"
+        f"{challenge_block}\n\n"
+        f"Current status:\n"
+        f"HP:{state.health:.0f}, Hunger:{state.hunger:.0f}, "
+        f"Thirst:{state.thirst:.0f}, Fear:{state.fear:.0f}/100.\n"
+        f"Resources: Wood:{state.wood}, Stone:{state.stone}, "
+        f"Food:{state.food}, Water:{state.water}.\n"
+        f"Equipped: Spear:{inv.spear}, Bow:{inv.bow}, "
+        f"Rod:{inv.fishingRod}, Boat:{inv.boat}.\n"
+        f"Camp Level: {state.baseCamp.level}. Position X: {state.playerX:.0f}.\n"
+        f"Environment: {'Night' if state.isNight else 'Day'}, "
+        f"Events: {', '.join(state.activeEvents) or 'None'}.\n"
+        f"Predator Nearby: {'YES - HIGH DANGER' if state.predatorNear else 'No'}.\n"
+        f"{f'ACTIVE CHALLENGE: {state.activeChallenge.name} ({state.activeChallenge.type}) — {state.activeChallenge.timeLimit}s left' if state.activeChallenge else 'No active challenge.'}\n\n"
+        f"Valid Actions: {VALID_ACTIONS}.\n\n"
+        'Respond ONLY with a raw JSON object — no markdown, no extra text. '
+        'Example: {"action":"FORAGE","thought":"Need wood and resources"} [/INST]'
+    )

start.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# start.sh
+# Boots FastAPI (background) then Nginx (foreground) inside the container.
+set -e
+
+echo "🏝️  Survival Island starting…"
+echo "    HF_MODEL : ${HF_MODEL:-not set}"
+echo "    HF_TOKEN : ${HF_TOKEN:+set (hidden)}"
+echo "    PORT     : ${PORT:-7860}"
+
+# ── 1. Start FastAPI on port 8000 (background) ────────────────────────────────
+uvicorn server.app:app \
+    --host 127.0.0.1 \
+    --port 8000 \
+    --workers 1 \
+    --log-level info &
+UVICORN_PID=$!
+
+# ── 2. Wait until FastAPI is healthy (up to 30 s) ─────────────────────────────
+echo "⏳  Waiting for FastAPI health check…"
+for i in $(seq 1 30); do
+    if curl -sf http://127.0.0.1:8000/api/health > /dev/null 2>&1; then
+        echo "✅  FastAPI ready after ${i}s."
+        break
+    fi
+    sleep 1
+done
+
+# ── 3. Start Nginx in foreground (keeps the container alive) ──────────────────
+echo "🚀  Nginx serving on :${PORT:-7860}"
+nginx -g "daemon off;"
+
+# ── 4. Cleanup on exit ────────────────────────────────────────────────────────
+echo "Nginx exited. Stopping uvicorn…"
+kill "$UVICORN_PID" 2>/dev/null || true