app.py

"""Working Spaces — browse Hugging Face Spaces that are not broken.

A census of the complete public catalogue found that 38.57% of non-static
Spaces sit in a permanent error state, and the Hub offers no way to filter
them out when browsing. This does that.

Index built from that census; every Space listed here was NOT in
BUILD_ERROR / RUNTIME_ERROR / CONFIG_ERROR / NO_APP_FILE at snapshot time.
"""

import gzip
import json
from pathlib import Path

import gradio as gr

INDEX = Path(__file__).with_name("spaces.jsonl.gz")
CENSUS_DATE = "2026-08-28"
PAGE = 50

# Stage meanings, stated plainly so the listing is not mistaken for a
# liveness guarantee. SLEEPING is included because it is idle, not failed --
# though our own probing could not confirm sleeping Spaces reliably wake, so
# it is labelled honestly rather than promised as working.
STAGE_NOTE = {
    "RUNNING": "running now",
    "SLEEPING": "idle — wakes on request (usually)",
    "PAUSED": "paused by author or quota",
    "BUILDING": "building",
    "APP_STARTING": "starting",
    "RUNNING_BUILDING": "running, rebuilding",
    "RUNNING_APP_STARTING": "running, restarting",
    "DELETING": "being deleted",
}


def load():
    rows = []
    with gzip.open(INDEX, "rt", encoding="utf-8") as fh:
        for line in fh:
            rows.append(json.loads(line))
    return rows


ROWS = load()
SDKS = sorted({r["sdk"] for r in ROWS if r["sdk"]})
STAGES = sorted({r["stage"] for r in ROWS if r["stage"]})


def search(query, sdk, stage, running_only, min_likes, page):
    q = (query or "").strip().lower()
    out = ROWS
    if running_only:
        out = [r for r in out if r["stage"].startswith("RUNNING")]
    elif stage and stage != "any":
        out = [r for r in out if r["stage"] == stage]
    if sdk and sdk != "any":
        out = [r for r in out if r["sdk"] == sdk]
    if min_likes:
        out = [r for r in out if r["likes"] >= min_likes]
    if q:
        out = [r for r in out if q in r["id"].lower()]

    total = len(out)
    page = max(1, int(page or 1))
    start = (page - 1) * PAGE
    rows = out[start:start + PAGE]

    table = [[
        f"[{r['id']}](https://huggingface.co/spaces/{r['id']})",
        r["sdk"] or "—",
        STAGE_NOTE.get(r["stage"], r["stage"]),
        r["likes"],
        r["modified"] or "—",
    ] for r in rows]

    pages = max(1, -(-total // PAGE))
    note = (f"**{total:,}** matches — page {min(page, pages)} of {pages:,}"
            if total else "No matches. Try clearing a filter.")
    return table, note


with gr.Blocks(title="Working Spaces") as demo:
    gr.Markdown(f"""
# Working Spaces

Browse Hugging Face Spaces **that are not broken**.

A census of the complete public catalogue on {CENSUS_DATE} found that
**38.57% of non-static Spaces are in a permanent error state** — 443,683 of
1,150,413. Only 2.85% report `RUNNING`. The Hub exposes runtime stage through
its API but does not let you filter on it while browsing, so this does.

Every Space below was **not** in `BUILD_ERROR`, `RUNTIME_ERROR`,
`CONFIG_ERROR`, or `NO_APP_FILE` at snapshot time. Static Spaces are excluded —
they have no runtime and cannot fail, so including them would flatter the
numbers.

*Index: {len(ROWS):,} Spaces. This is a snapshot, not live state — a Space
listed here may have broken since.*
""")

    with gr.Row():
        query = gr.Textbox(label="Search name or author", scale=3,
                           placeholder="whisper, stable-diffusion, your-username…")
        sdk = gr.Dropdown(["any"] + SDKS, value="any", label="SDK", scale=1)
        stage = gr.Dropdown(["any"] + STAGES, value="any", label="Stage", scale=1)
    with gr.Row():
        running_only = gr.Checkbox(label="Only RUNNING right now (2.85% of the catalogue)")
        min_likes = gr.Slider(0, 100, value=0, step=1, label="Minimum likes")
        page = gr.Number(value=1, label="Page", precision=0, minimum=1)

    go = gr.Button("Search", variant="primary")
    note = gr.Markdown()
    table = gr.Dataframe(
        headers=["Space", "SDK", "Stage", "Likes", "Last modified"],
        datatype=["markdown", "str", "str", "number", "str"],
        interactive=False, wrap=True,
    )

    gr.Markdown("""
---
**Method and caveats.** Built from a complete enumeration of the public Spaces
catalogue (1,458,692 Spaces, 778,898 authors), using the `runtime.stage` field
Hugging Face publishes through its own API — nothing here is scraped or
inferred. Of 1,999 Spaces reporting `RUNNING` that we probed over HTTP, 91.5%
returned 200, so `RUNNING` means what it says.

`SLEEPING` Spaces are included and labelled as idle. Our attempt to verify
that they reliably wake was **inconclusive** — on a single request about half
returned a 2xx and half a 503, and two runs over the same sample disagreed. So
treat "wakes on request" as usually-true rather than guaranteed.

Data: [Ashsinha1/hf-spaces-census](https://huggingface.co/datasets/Ashsinha1/hf-spaces-census) ·
Code: [dataset-integrity-audit](https://github.com/ashishsinha1602/dataset-integrity-audit)
""")

    inputs = [query, sdk, stage, running_only, min_likes, page]
    go.click(search, inputs=inputs, outputs=[table, note])
    query.submit(search, inputs=inputs, outputs=[table, note])
    demo.load(search, inputs=inputs, outputs=[table, note])

if __name__ == "__main__":
    demo.launch()