feat(hf-space): add HuggingFace backend (Gemma/Phi-4) alongside Anthropic

Users without an ANTHROPIC_API_KEY can now run the diagnostic via an
open-weight model served through the HuggingFace Inference Providers
API. On a deployed HuggingFace Space, the Space's identity provides
free monthly inference credits, so no credentials are needed at all —
this is the zero-signup path for trying the diagnostic.

What changed:
app.py
- _detect_provider(env) — env-driven dispatcher (MODEL_PROVIDER >
ANTHROPIC_API_KEY > HF_TOKEN/HUGGING_FACE_HUB_TOKEN/SPACE_ID >
anthropic default). Captured at module load as DEFAULT_PROVIDER.
- _call_anthropic(system, user) and _call_huggingface(system, user)
— two interchangeable backends behind a thin _call_model dispatcher.
HF uses huggingface_hub.InferenceClient.chat_completion with
temperature=0.2 to keep JSON output stable on smaller models.
- diagnose() takes a new provider parameter, defaulting to
DEFAULT_PROVIDER. The Gradio UI now has a Model-provider dropdown
so users can A/B the two backends at runtime.
- F14 error message now includes the provider + model name and
suggests switching providers in the dropdown as a fallback action.
- Fixed a nesting bug in the word-count validator that the same
edit pass introduced (MAX check ended up dead code inside the MIN
branch).

requirements.txt
+ huggingface_hub>=0.27

.env.example
Restructured into sections — provider selection (MODEL_PROVIDER),
Anthropic backend (ANTHROPIC_API_KEY, MODEL_ID), HuggingFace backend
(HF_TOKEN, HF_MODEL_ID with tested alternatives documented inline),
validation (MAX_DESCRIPTION_WORDS).

test_diagnose.py
+ 9 _detect_provider tests covering all five branches of the
env-driven dispatch + case-insensitivity + invalid-explicit
fall-through + multiple HF token var names.
+ 3 _call_model dispatch tests using monkeypatch.setitem on the
PROVIDERS dict (no SDK mocks — Principle VII exempts API calls).
All 27 tests pass (15 prior parser + 12 new provider).

specs/004-berkshire-test/contracts/hf-space-interface.md §2
Rewrote §2 to document both backends side by side, including the
provider-selection precedence table, the HF InferenceClient
invocation pattern, tested model choices, the lack of HF prefix
caching, and the unified F14 failure-mode messaging.

specs/004-berkshire-test/tasks.md T037-T039
T037 rationale updated to reflect the extension. T038 and T039
smoke-test instructions updated to cover both providers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env.example

@@ -1,14 +1,52 @@
-# Copy to .env (gitignored) and fill in your Anthropic API key for local development.
-# On HuggingFace Spaces, set these as Space secrets in the Settings panel.
+# Copy to .env (gitignored). The Space supports TWO model backends; you
+# only need credentials for whichever one(s) you want to use. On the
+# deployed HuggingFace Space, leave .env empty and set these as Space
+# secrets in the Settings panel instead.
+#
+# ============================================================
+# PROVIDER SELECTION
+# ============================================================
+# Optional. If unset, the app auto-detects based on which credentials
+# are present (see app.py::_detect_provider). Valid values:
+#   anthropic    — Claude via the Anthropic SDK (best writeup quality)
+#   huggingface  — Gemma 2 / Phi-4 / Llama-3.3 / Qwen via HF Inference
+#                  Providers (works with no Anthropic key; free on
+#                  HF Spaces via the Space's identity)
+# Leave blank for auto-detect.
+# MODEL_PROVIDER=
 
+# ============================================================
+# ANTHROPIC BACKEND
+# ============================================================
+# Required for the anthropic backend. Get one at console.anthropic.com.
 ANTHROPIC_API_KEY=your-anthropic-api-key-here
 
-# Optional overrides (defaults in app.py — claude-opus-4-7 is what
-# produces materially better diagnostic writeups; claude-sonnet-4-6
-# is a cost-optimized fallback that should be benchmarked against
-# Opus on real submissions before flipping. See research.md R15.)
+# Optional. claude-opus-4-7 is the default — produces materially better
+# diagnostic writeups. claude-sonnet-4-6 is a cost-optimized fallback;
+# benchmark before flipping (research.md R15).
 MODEL_ID=claude-opus-4-7
 
+# ============================================================
+# HUGGINGFACE BACKEND
+# ============================================================
+# Optional locally — get one at huggingface.co/settings/tokens. NOT
+# required on a deployed HuggingFace Space (the Space identity is used
+# automatically and includes free monthly inference credits).
+# HF_TOKEN=your-hf-token-here
+
+# Optional. Default google/gemma-2-9b-it works well and is widely
+# available on HF Inference Providers. Other tested choices:
+#   microsoft/Phi-4-mini-instruct      — smaller, faster, decent JSON
+#   meta-llama/Llama-3.3-70B-Instruct  — slower, very high quality
+#   Qwen/Qwen2.5-72B-Instruct          — strong on structured output
+# Smaller open models can be looser than Claude on schema adherence;
+# the parser raises MalformedResponseError on bad output and the UI
+# shows a "try again" message rather than crashing.
+# HF_MODEL_ID=google/gemma-2-9b-it
+
+# ============================================================
+# VALIDATION
+# ============================================================
 # Word-count cap on the description Textbox. The Gradio validator
 # rejects submissions outside 200–MAX_DESCRIPTION_WORDS.
 MAX_DESCRIPTION_WORDS=5000

app.py

@@ -5,8 +5,16 @@ the two-axis Berkshire Test for AI and returns a scored writeup.
 
 Architecture per specs/004-berkshire-test/contracts/hf-space-interface.md:
   - Inputs: a description (200–5000 words) + 3 optional clarifiers.
-  - One Anthropic call with the system block (REFERENCE_BLOCK) marked
-    cache_control:ephemeral; subsequent calls hit the 5-minute cache.
+  - Two backends, selectable by env (`MODEL_PROVIDER`) or auto-detected
+    from available credentials:
+      * anthropic   — Claude Opus / Sonnet via the Anthropic SDK;
+                      system block is `cache_control:ephemeral` so
+                      subsequent calls hit the 5-minute prefix cache.
+      * huggingface — Open models (Gemma 2 9B by default, swappable to
+                      Phi-4, Llama-3.3, Qwen 2.5, etc.) via the
+                      huggingface_hub InferenceClient. Works on HF
+                      Spaces with the Space's free inference credits;
+                      locally requires HF_TOKEN.
   - Output: two Gradio tabs — markdown writeup + raw JSON.
 
 Engine/Site boundary (Principle VIII): this app lives in gradio-apps/
@@ -171,10 +179,107 @@ def parse_response(raw: str) -> Response:
 
 ROOT = Path(__file__).parent
 
-MODEL_ID = os.environ.get("MODEL_ID", "claude-opus-4-7")
+ANTHROPIC_MODEL_ID = os.environ.get("MODEL_ID", "claude-opus-4-7")
+HF_MODEL_ID = os.environ.get("HF_MODEL_ID", "google/gemma-2-9b-it")
 MAX_DESCRIPTION_WORDS = int(os.environ.get("MAX_DESCRIPTION_WORDS", "5000"))
 MIN_DESCRIPTION_WORDS = 200
 
+
+# ---------------------------------------------------------------------------
+# Provider abstraction (anthropic vs huggingface — selectable at runtime)
+# ---------------------------------------------------------------------------
+
+
+def _detect_provider(env=None) -> str:
+    """Pick a model provider from env. Order of precedence:
+      1. Explicit MODEL_PROVIDER (anthropic | huggingface).
+      2. Presence of ANTHROPIC_API_KEY → anthropic.
+      3. Presence of HF_TOKEN / HUGGING_FACE_HUB_TOKEN, or running on
+         a HuggingFace Space (SPACE_ID set) → huggingface.
+      4. Fall through to anthropic (call-time error will tell the user
+         which env to set).
+    """
+    env = env if env is not None else os.environ
+    explicit = env.get("MODEL_PROVIDER", "").strip().lower()
+    if explicit in ("anthropic", "huggingface"):
+        return explicit
+    if env.get("ANTHROPIC_API_KEY"):
+        return "anthropic"
+    if (
+        env.get("HF_TOKEN")
+        or env.get("HUGGING_FACE_HUB_TOKEN")
+        or env.get("SPACE_ID")
+    ):
+        return "huggingface"
+    return "anthropic"
+
+
+def _call_anthropic(system_block: str, user_prompt: str) -> str:
+    """Anthropic backend. System block is cache-marked; the user prompt
+    is sent fresh. Returns the raw assistant text."""
+    from anthropic import Anthropic
+
+    client = Anthropic()
+    resp = client.messages.create(
+        model=ANTHROPIC_MODEL_ID,
+        max_tokens=2500,
+        system=[
+            {
+                "type": "text",
+                "text": system_block,
+                "cache_control": {"type": "ephemeral"},
+            }
+        ],
+        messages=[{"role": "user", "content": user_prompt}],
+    )
+    return resp.content[0].text
+
+
+def _call_huggingface(system_block: str, user_prompt: str) -> str:
+    """HuggingFace backend. Uses the unified chat_completion interface,
+    which routes through HF Inference Providers and supports Gemma 2,
+    Phi-4-mini-instruct, Llama-3.3, Qwen 2.5, and many others. Lower
+    temperature (0.2) than the SDK default to keep JSON output stable —
+    smaller open models can be looser than Claude on schema adherence.
+    """
+    from huggingface_hub import InferenceClient
+
+    token = (
+        os.environ.get("HF_TOKEN")
+        or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    )
+    client = InferenceClient(model=HF_MODEL_ID, token=token, timeout=120)
+    resp = client.chat_completion(
+        messages=[
+            {"role": "system", "content": system_block},
+            {"role": "user", "content": user_prompt},
+        ],
+        max_tokens=2500,
+        temperature=0.2,
+    )
+    return resp.choices[0].message.content
+
+
+PROVIDERS = {
+    "anthropic": _call_anthropic,
+    "huggingface": _call_huggingface,
+}
+
+
+def _call_model(system_block: str, user_prompt: str, provider: str) -> str:
+    """Dispatch to the named provider. Raises ValueError on unknown
+    provider; callers are expected to validate before calling."""
+    if provider not in PROVIDERS:
+        raise ValueError(
+            f"Unknown provider: {provider!r}; expected one of {sorted(PROVIDERS)}"
+        )
+    return PROVIDERS[provider](system_block, user_prompt)
+
+
+# Auto-detected once at module import; the Gradio UI exposes a runtime
+# override via the Provider dropdown.
+DEFAULT_PROVIDER = _detect_provider()
+
 INDUSTRIES = [
     "insurance", "banking", "healthcare", "retail", "manufacturing",
     "logistics", "agriculture", "energy", "telecom", "media",
@@ -236,10 +341,15 @@ def diagnose(
     industry: Optional[str],
     scale: Optional[str],
     budget: Optional[str],
+    provider: Optional[str] = None,
 ) -> tuple[str, str]:
-    """Validate input, call Anthropic with the cached system block, parse
-    the response, and return (markdown_writeup, raw_json_string) for the
-    two Gradio tabs.
+    """Validate input, call the selected model with the cached system
+    block, parse the response, and return (markdown_writeup,
+    raw_json_string) for the two Gradio tabs.
+
+    `provider` (anthropic | huggingface) defaults to DEFAULT_PROVIDER
+    when not supplied — the Gradio dropdown always supplies it on a
+    real submission.
 
     Per F14 + contract §2, all error paths surface a user-friendly message
     in the markdown tab and an empty JSON tab; nothing leaks a stack trace.
@@ -263,6 +373,14 @@ def diagnose(
             "",
         )
 
+    provider = provider or DEFAULT_PROVIDER
+    if provider not in PROVIDERS:
+        return (
+            f"⚠ Unknown model provider {provider!r}. Pick one of "
+            f"{sorted(PROVIDERS)} from the dropdown.",
+            "",
+        )
+
     user_prompt = (
         PROMPT_TEMPLATE
         .replace("{{user_input}}", description)
@@ -272,29 +390,15 @@ def diagnose(
     )
 
     try:
-        # Lazy-import the SDK so test_diagnose.py can import this module
-        # without requiring the anthropic package at test time.
-        from anthropic import Anthropic
-
-        client = Anthropic()
-        resp = client.messages.create(
-            model=MODEL_ID,
-            max_tokens=2500,
-            system=[
-                {
-                    "type": "text",
-                    "text": SYSTEM_BLOCK,
-                    "cache_control": {"type": "ephemeral"},
-                }
-            ],
-            messages=[{"role": "user", "content": user_prompt}],
-        )
-        raw = resp.content[0].text
+        raw = _call_model(SYSTEM_BLOCK, user_prompt, provider)
     except Exception as e:
-        # Anthropic API timeout / rate limit / auth / server / network failure
+        # API timeout / rate limit / auth / server / network failure
+        # (Anthropic SDK or huggingface_hub InferenceClient).
+        model_label = ANTHROPIC_MODEL_ID if provider == "anthropic" else HF_MODEL_ID
         return (
-            f"⚠ The diagnostic call failed ({type(e).__name__}). Try again in a moment, "
-            f"or shorten your description.",
+            f"⚠ The diagnostic call to {provider} ({model_label}) failed "
+            f"({type(e).__name__}). Try again in a moment, switch providers in "
+            f"the dropdown, or shorten your description.",
             "",
         )
 
@@ -333,6 +437,11 @@ def build_demo():
     """Build and return the Gradio Blocks UI. Called only by __main__."""
     import gradio as gr
 
+    provider_choices = [
+        (f"Anthropic — {ANTHROPIC_MODEL_ID} (requires ANTHROPIC_API_KEY)", "anthropic"),
+        (f"HuggingFace — {HF_MODEL_ID} (free on HF Spaces; HF_TOKEN locally)", "huggingface"),
+    ]
+
     with gr.Blocks(title="The Compounding Test") as demo:
         gr.Markdown(
             "# The Compounding Test\n\n"
@@ -340,7 +449,10 @@ def build_demo():
             "description of your AI initiative (200–5000 words); receive a scored "
             "writeup in one of four quadrants — compounder, one-shot win, compounding "
             "the wrong thing, or Roman Candle. The framework is at "
-            "https://www.mile-hi.ai/journal/the-berkshire-test"
+            "https://www.mile-hi.ai/journal/the-berkshire-test\n\n"
+            f"_Default model provider: **{DEFAULT_PROVIDER}** "
+            f"(auto-detected from your environment — pick a different one in the "
+            f"dropdown below to compare)._"
         )
         with gr.Row():
             description = gr.Textbox(
@@ -356,6 +468,19 @@ def build_demo():
             industry = gr.Dropdown(INDUSTRIES, label="Industry (optional)", value=None)
             scale = gr.Dropdown(SCALES, label="Scale (optional)", value=None)
             budget = gr.Dropdown(BUDGETS, label="Budget tier (optional)", value=None)
+        with gr.Row():
+            provider = gr.Dropdown(
+                choices=provider_choices,
+                value=DEFAULT_PROVIDER,
+                label="Model provider",
+                info=(
+                    "Claude gives the highest-quality writeups but needs your "
+                    "own ANTHROPIC_API_KEY. The HuggingFace backend runs on a "
+                    "smaller open-weight model and works on a deployed HF Space "
+                    "without any keys, so it's the easiest way to try the "
+                    "diagnostic without signing up for anything."
+                ),
+            )
         submit = gr.Button("Diagnose", variant="primary")
         with gr.Tabs():
             with gr.Tab("Diagnosis"):
@@ -364,7 +489,7 @@ def build_demo():
                 json_out = gr.Code(language="json")
         submit.click(
             diagnose,
-            inputs=[description, industry, scale, budget],
+            inputs=[description, industry, scale, budget, provider],
             outputs=[writeup_out, json_out],
         )
 

requirements.txt

@@ -1,4 +1,5 @@
 gradio>=4.0
 anthropic>=0.39
+huggingface_hub>=0.27
 python-dotenv>=1.0
 pytest>=8.0

test_diagnose.py

@@ -9,7 +9,13 @@ from __future__ import annotations
 
 import pytest
 
-from app import MalformedResponseError, parse_response
+from app import (
+    MalformedResponseError,
+    PROVIDERS,
+    _call_model,
+    _detect_provider,
+    parse_response,
+)
 
 
 # --- Fixtures ---------------------------------------------------------------
@@ -168,6 +174,76 @@ def test_extra_unknown_fields_tolerated():
     assert r.quadrant == "compounder"
 
 
+# --- Provider auto-detection (multi-backend support) ----------------------
+
+
+def test_detect_provider_explicit_anthropic_wins():
+    env = {"MODEL_PROVIDER": "anthropic", "HF_TOKEN": "hf-xxx"}
+    assert _detect_provider(env) == "anthropic"
+
+
+def test_detect_provider_explicit_huggingface_wins():
+    env = {"MODEL_PROVIDER": "huggingface", "ANTHROPIC_API_KEY": "sk-xxx"}
+    assert _detect_provider(env) == "huggingface"
+
+
+def test_detect_provider_case_insensitive():
+    assert _detect_provider({"MODEL_PROVIDER": "HuggingFace"}) == "huggingface"
+
+
+def test_detect_provider_invalid_explicit_falls_through():
+    # bogus MODEL_PROVIDER is ignored; auto-detect kicks in
+    env = {"MODEL_PROVIDER": "bogus", "ANTHROPIC_API_KEY": "sk-xxx"}
+    assert _detect_provider(env) == "anthropic"
+
+
+def test_detect_provider_anthropic_when_only_anthropic_key_set():
+    assert _detect_provider({"ANTHROPIC_API_KEY": "sk-xxx"}) == "anthropic"
+
+
+def test_detect_provider_huggingface_when_only_hf_token_set():
+    assert _detect_provider({"HF_TOKEN": "hf-xxx"}) == "huggingface"
+
+
+def test_detect_provider_huggingface_when_running_on_hf_space():
+    # HF Spaces sets SPACE_ID automatically and provides free inference credits
+    assert _detect_provider({"SPACE_ID": "mile-hi-ai/compounding-test"}) == "huggingface"
+
+
+def test_detect_provider_alt_hf_token_var():
+    # HuggingFace SDKs also recognize HUGGING_FACE_HUB_TOKEN
+    assert _detect_provider({"HUGGING_FACE_HUB_TOKEN": "hf-xxx"}) == "huggingface"
+
+
+def test_detect_provider_default_when_nothing_set():
+    # No creds anywhere → default to anthropic (clearest error at call time)
+    assert _detect_provider({}) == "anthropic"
+
+
+# --- Provider dispatch (_call_model routes to the right backend) -----------
+
+
+def test_call_model_routes_to_anthropic_backend(monkeypatch):
+    calls = []
+    monkeypatch.setitem(PROVIDERS, "anthropic", lambda s, u: (calls.append(("anthropic", s, u)) or "anth-out"))
+    out = _call_model("system-text", "user-text", "anthropic")
+    assert out == "anth-out"
+    assert calls == [("anthropic", "system-text", "user-text")]
+
+
+def test_call_model_routes_to_huggingface_backend(monkeypatch):
+    calls = []
+    monkeypatch.setitem(PROVIDERS, "huggingface", lambda s, u: (calls.append(("hf", s, u)) or "hf-out"))
+    out = _call_model("system-text", "user-text", "huggingface")
+    assert out == "hf-out"
+    assert calls == [("hf", "system-text", "user-text")]
+
+
+def test_call_model_unknown_provider_raises():
+    with pytest.raises(ValueError, match="provider"):
+        _call_model("s", "u", "bogus-provider")
+
+
 def test_warnings_populated_for_failure_quadrant():
     raw = VALID_JSON_BLOCK.replace('"quadrant": "compounder"', '"quadrant": "roman-candle"').replace(
         '"warnings": []',