══════════════════════════════════════════════════════════════
  JARVIS → HUGGINGFACE UPLOAD GUIDE
  16 GB RAM · Local inference · No GPU required
══════════════════════════════════════════════════════════════

WHAT'S IN THIS FOLDER (hf_jarvis/)
────────────────────────────────────────────────────────────
  app.py          → Gradio UI (entry point for HF Spaces)
  brain.py        → HuggingFace Transformers inference engine
  memory.py       → SQLite memory (facts + conversation history)
  thinking.py     → Background anticipation engine
  voice_tts.py    → Edge-TTS voice output
  config.py       → All settings via environment variables
  requirements.txt→ All pip packages needed
  README.md       → HuggingFace model card (auto-displayed)
  .env.example    → Local dev environment template
  .gitignore      → Keeps your DB and secrets out of git

════════════════════════════════════════════════════════════
STEP 1: CREATE A HUGGINGFACE ACCOUNT / LOG IN
════════════════════════════════════════════════════════════
  Go to: https://huggingface.co
  Sign up (free) or log in.

════════════════════════════════════════════════════════════
STEP 2: CREATE A NEW SPACE
════════════════════════════════════════════════════════════
  1. Click your profile icon → New Space
  2. Space name:    jarvis          (or any name you like)
  3. License:       MIT
  4. SDK:           Gradio          ← IMPORTANT: select Gradio
  5. Hardware:      CPU (upgraded)  ← free tier is fine for 3.8B 4-bit
     For Mistral-7B choose "CPU upgrade" or "A10G small" if available
  6. Visibility:   Private (or Public — your choice)
  7. Click: Create Space

════════════════════════════════════════════════════════════
STEP 3: UPLOAD FILES
════════════════════════════════════════════════════════════
  METHOD A — Drag-and-drop in browser (easiest)
  ──────────────────────────────────────────────
  1. Open your Space page → click "Files" tab
  2. Click "Add file" → "Upload files"
  3. Select ALL files from this folder:
       app.py
       brain.py
       memory.py
       thinking.py
       voice_tts.py
       config.py
       requirements.txt
       README.md
       .env.example
       .gitignore
  4. Click "Commit changes to main"
  5. HuggingFace will install requirements.txt and launch app.py
     automatically. Wait ~2-5 minutes for the build to finish.

  METHOD B — Git push (recommended for updates)
  ───────────────────────────────────────────────
  Run in PowerShell from the hf_jarvis\ folder:

    git init
    git remote add origin https://huggingface.co/spaces/<YOUR_USERNAME>/jarvis
    git add .
    git commit -m "Initial JARVIS upload"
    git push origin main

  (You may need: git lfs install  if you ever add large model files)

════════════════════════════════════════════════════════════
STEP 4: SET ENVIRONMENT VARIABLES (optional but recommended)
════════════════════════════════════════════════════════════
  In your Space page → Settings tab → Variables & Secrets

  Add these if you want to customize:
    JARVIS_MODEL  = microsoft/Phi-3-mini-4k-instruct  (default)
    JARVIS_QUANT  = 4bit                              (default)
    JARVIS_THINKING = true

  Leave blank to use the safe defaults already in config.py.

════════════════════════════════════════════════════════════
STEP 5: WAIT FOR BUILD & OPEN JARVIS
════════════════════════════════════════════════════════════
  HuggingFace will show build logs. When it says "Running",
  your JARVIS is live at:

    https://huggingface.co/spaces/<YOUR_USERNAME>/jarvis

  First response takes ~30-90 seconds (model loading).
  Every subsequent message is fast.

════════════════════════════════════════════════════════════
WHAT JARVIS CAN DO ON HUGGINGFACE
════════════════════════════════════════════════════════════
  ✅ Chat with 3.8B / 7B local model — no external API costs
  ✅ Voice replies (Edge-TTS, Microsoft GuyNeural voice)
  ✅ Remember facts: type "remember name is Tony"
  ✅ Check status: type "status"
  ✅ See predictions: type "anticipate"
  ✅ Persistent memory across sessions (SQLite DB, local to the Space)
  ✅ Runs on 16 GB RAM — Phi-3-mini 4-bit uses only ≈3-4 GB

════════════════════════════════════════════════════════════
RAM & MODEL OPTIONS
════════════════════════════════════════════════════════════
  Your 16 GB gives you a LOT of headroom:

  Model                              │ Quant │ RAM used
  ───────────────────────────────────┼───────┼──────────
  Phi-3-mini-4k-instruct (3.8B)     │ 4-bit │ ~3-4 GB  ← default (fast)
  Phi-3-mini-4k-instruct (3.8B)     │ fp16  │ ~7.6 GB
  Mistral-7B-Instruct-v0.2 (7B)     │ 4-bit │ ~4-5 GB  ← deep reasoning
  Mistral-7B-Instruct-v0.2 (7B)     │ fp16  │ ~14 GB   ← max quality

  To switch: set JARVIS_MODEL in Space Settings.

════════════════════════════════════════════════════════════
TROUBLESHOOTING
════════════════════════════════════════════════════════════
  "Model loading..." forever
    → First load downloads from HF Hub. Wait 3-5 minutes.
      The model (~2-7 GB) downloads once and is cached.

  "bitsandbytes not available"
    → 4-bit quant needs a recent version. Set JARVIS_QUANT=none
      if bitsandbytes fails (fp32, uses more RAM but works).

  Out of memory
    → Set JARVIS_QUANT=4bit (default) to reduce RAM to ~3-4 GB.

  Voice not working
    → edge-tts needs internet. On fully offline HF Spaces,
      TTS falls back silently to text-only — chat still works.

══════════════════════════════════════════════════════════════
  SIR — YOUR JARVIS IS READY FOR THE WORLD
══════════════════════════════════════════════════════════════