feat: HuggingFace Spaces — live public demo with zero-API-key mode

[Neal006]

Background

HuggingFace Spaces is the standard way to publish live ML demos. Deploying MemoryLens there gives the project a live public URL — no installation required for visitors. HF Spaces with the Streamlit SDK requires the main entry file to be named app.py. MemoryLens already has a full Streamlit dashboard at dashboard.py; this issue is about wiring it up correctly for HF Spaces.

What to build

app.py — new file at project root

This file delegates all logic to dashboard.py to avoid code duplication:

"""
HuggingFace Spaces entry point.

HF Spaces Streamlit SDK requires the main application file to be named app.py.
This file delegates all logic to dashboard.py to avoid code duplication.
"""
import os
import runpy

runpy.run_path(
    os.path.join(os.path.dirname(os.path.abspath(__file__)), "dashboard.py"),
    run_name="__main__",
)

README.md — prepend YAML frontmatter

Add this block before the existing # MemoryLens heading (HuggingFace reads it to configure the Space):

---
title: MemoryLens
emoji: 🔭
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: "1.35.0"
app_file: app.py
pinned: false
license: mit
---

dashboard.py — read-only mode guard

At the top of dashboard.py, after imports, add a check:

_has_provider = bool(
    os.getenv("GROQ_API_KEY") or os.getenv("OPENAI_API_KEY") or
    os.getenv("ANTHROPIC_API_KEY") or os.getenv("OPENROUTER_API_KEY")
)

Wrap the "▶ Run Live" button in if _has_provider: and add an info banner when no keys are set:

if not _has_provider:
    st.info(
        "🔭 Running in demo mode — no API key detected. "
        "Set GROQ_API_KEY (or any other provider key) in .env to run a live benchmark. "
        "Click **Load Demo** below to explore pre-computed results."
    )

The Load Demo button (which loads demo_results.json) must always be visible regardless of API key status.

Verify quick_demo.py

Run python quick_demo.py --quiet and confirm it:

1. Completes without any API key
2. Writes/updates demo_results.json

If it already works (it should), no changes needed — just document this in the PR.

Acceptance criteria

• app.py exists at project root
• streamlit run app.py launches the dashboard identically to streamlit run dashboard.py
• README.md has the HF Spaces YAML frontmatter block as the first lines of the file
• Dashboard shows st.info banner when no API keys are in the environment
• "Load Demo" button still works in read-only mode
• python quick_demo.py --quiet completes without API key and regenerates demo_results.json
• All existing tests still pass

Technical hints

• runpy.run_path(..., run_name="__main__") executes dashboard.py as if it were the main script — this is the standard way to delegate to another Streamlit file without duplicating code
• The YAML frontmatter must be the very first lines of README.md (before any Markdown)
• HF Spaces sdk_version should match the version in requirements.txt — check them both

Getting started

# Test the read-only guard:
GROQ_API_KEY="" OPENAI_API_KEY="" ANTHROPIC_API_KEY="" streamlit run app.py
# Should show the info banner and Load Demo button; Run Live button should be hidden

# Verify quick_demo runs without API key:
python quick_demo.py --quiet
cat demo_results.json | python -c "import sys,json; d=json.load(sys.stdin); print(list(d.keys()))"

This is a beginner-friendly issue — most of the work is writing ~10 lines of Python and editing the README. A great first contribution!