File size: 11,080 Bytes
37ca45a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4e4180a
37ca45a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4e4180a
37ca45a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
"""modelread MCP: a Gradio Space whose functions are MCP tools (mcp_server=True), so it can be added from
huggingface.co/settings/mcp and used by any MCP client. Thin client over the modelread API; deterministic (no LLM).

Env (Space secrets, never in code): MODELREAD_PROXY_SECRET marks this Space as a trusted front end so the API
rate-limits per viewer. MODELREAD_API overrides the upstream.
"""

from __future__ import annotations

import os

import gradio as gr
import httpx

API = os.environ.get("MODELREAD_API", "https://modelread.159.223.102.247.nip.io").rstrip("/")
SECRET = os.environ.get("MODELREAD_PROXY_SECRET", "")
SITE = "https://modelread.com"
_http = httpx.Client(timeout=httpx.Timeout(connect=10, read=150, write=20, pool=10), follow_redirects=True)


def _headers(request: gr.Request | None) -> dict:
    h = {"user-agent": "modelread-mcp-space/1", "accept": "application/json"}
    if SECRET:
        h["x-modelread-proxy"] = SECRET
        ip = ""
        if request is not None:
            ip = (request.headers.get("x-forwarded-for") or "").split(",")[0].strip()
        h["x-modelread-client"] = ("hfmcp:" + ip)[:64]
    return h


def _get(path: str, params: dict, request: gr.Request | None):
    r = _http.get(API + path, params={k: v for k, v in params.items() if v not in (None, "")}, headers=_headers(request))
    if r.status_code == 202:
        return {"status": "queued", "detail": "modelread is reading this repository from the Hub for the first time; "
                                              "call again in about a minute."}
    if r.status_code == 429:
        return {"status": "rate_limited", "detail": "too many requests; retry in a minute"}
    try:
        body = r.json()
    except ValueError:
        body = {"detail": r.text[:300]}
    if r.status_code >= 400:
        return {"status": "error", "http_status": r.status_code, "detail": body.get("detail", body) if isinstance(body, dict) else body}
    return body


def _slim(v: dict | None) -> dict | None:
    if not v:
        return None
    keep = ("repo", "variant", "format", "verdict", "summary", "confidence", "ctx", "max_ctx_fit", "bits_per_weight",
            "decode_tps", "prefill_tps", "placement_bytes", "budgets", "launch", "reasons", "unknowns", "warnings",
            "notes", "runtime_support", "hub_url")
    return {k: v.get(k) for k in keep if k in v}


def estimate_fit(repo: str, hardware: str = "rtx4090", ctx: int = 32768, kv_cache_dtype: str = "f16",
                 request: gr.Request = None) -> dict:
    """Will this Hugging Face model run on this hardware, how fast, with which quant, and with what command?

    Checks the repo and its quantized derivatives (GGUF / MLX / AWQ / FP8) from their real file sizes and tensor
    headers. Returns the best variant and alternatives, each with: verdict (fits | fits-tight | offload | no | unknown),
    decode and prefill tokens/sec as a calibrated range (lo/mid/hi with basis), longest context that fits, memory
    placement (VRAM / RAM / SSD) and an exact llama.cpp / vLLM / MLX launch command.

    Args:
        repo: Hugging Face repo id, e.g. "Qwen/Qwen3.6-27B" or "unsloth/gemma-4-26B-A4B-it-GGUF".
        hardware: device preset id ("rtx4090", "m4max-128", "dgx-spark", "8x-h100-sxm", "iphone-17pro-12"),
            "2x-rtx3090", free text ("MacBook Pro M3 Max 128GB", "AWS g6e.xlarge"), or "gpu=24,ram=64,bw=936".
        ctx: context length in tokens to fit (default 32768).
        kv_cache_dtype: KV cache type: "f16", "q8_0" or "q4_0".
    """
    d = _get("/api/estimate", {"repo": repo.strip(), "hw": hardware.strip(), "ctx": int(ctx), "kv": kv_cache_dtype}, request)
    if not isinstance(d, dict) or "best" not in d:
        return d
    return {"repo": d.get("repo"), "hardware": d.get("hardware"), "ctx": d.get("ctx"), "model": d.get("model"),
            "best": _slim(d.get("best")), "alternatives": [_slim(a) for a in (d.get("alternatives") or [])[:4]],
            "notes": d.get("notes", []), "page": f"{SITE}/m/{repo.strip()}"}


def compare_hardware(repo: str, hardware_list: str = "rtx4090, m4max-128, dgx-spark, h100-sxm", ctx: int = 32768,
                     request: gr.Request = None) -> dict:
    """Run one Hugging Face model against several devices and rank them (best first).

    Use for "which of my machines should run X" or "is a 4090 or an M4 Max better for X".

    Args:
        repo: Hugging Face repo id, e.g. "openai/gpt-oss-120b".
        hardware_list: comma-separated devices (preset ids or free text), up to 8.
        ctx: context length in tokens (default 32768).
    """
    rows = []
    rank = {"fits": 0, "fits-tight": 1, "offload": 2, "unknown": 3, "no": 4}
    for hw in [h.strip() for h in hardware_list.split(",") if h.strip()][:8]:
        d = _get("/api/estimate", {"repo": repo.strip(), "hw": hw, "ctx": int(ctx)}, request)
        b = (d or {}).get("best") if isinstance(d, dict) else None
        if not b:
            rows.append({"hardware": hw, "error": (d or {}).get("detail") if isinstance(d, dict) else str(d)})
            continue
        rows.append({"hardware": d.get("hardware"), "verdict": b.get("verdict"), "repo": b.get("repo"),
                     "variant": b.get("variant"), "decode_tps": b.get("decode_tps"), "max_ctx_fit": b.get("max_ctx_fit"),
                     "launch": b.get("launch")})
    rows.sort(key=lambda r: (rank.get(r.get("verdict"), 5), -((r.get("decode_tps") or {}).get("mid") or 0)))
    return {"repo": repo, "ctx": ctx, "results": rows}


def find_models(question: str, default_hardware: str = "", request: gr.Request = None) -> dict:
    """Recommend open models for a task on a device, from a natural-language question.

    Ranks ~20k indexed Hugging Face models by fit, task benchmark percentile (vendor vs independent kept apart),
    quant quality and speed. Examples: "best coding model for an RTX 4090 + 64GB RAM at 32k context",
    "Japanese chat on a Galaxy S25 Ultra", "serve 8 users on 2x RTX 3090".

    Args:
        question: the request in plain words; name the device in it, or set default_hardware.
        default_hardware: device used when the question names none (preset id, e.g. "m4max-128").
    """
    r = _http.post(API + "/api/ask", json={"q": question, "llm": False, "hw": default_hardware or None},
                   headers=_headers(request))
    if r.status_code >= 400:
        return {"status": "error", "http_status": r.status_code, "detail": r.text[:300]}
    d = r.json()
    return {"query": d.get("query"), "answer_markdown": d.get("answer_md"), "notes": d.get("notes"),
            "results": [{"repo": x.get("repo"), "quality": (x.get("quality") or {}).get("quality"),
                         "best": _slim(x.get("best"))} for x in d.get("results", [])]}


def list_hardware(filter: str = "", limit: int = 40, request: gr.Request = None) -> list:
    """List device presets: GPUs of every vendor, Apple Silicon, multi-GPU nodes, cloud instances (with $/hour),
    Jetson, phones, tablets, single-board computers and VPS tiers.

    Args:
        filter: words matched against id / name / vendor / segment, e.g. "h100", "amd datacenter", "phone samsung".
        limit: maximum rows to return.
    """
    rows = _get("/api/hardware", {}, request)
    if not isinstance(rows, list):
        return [rows]
    words = filter.lower().split()
    out = [r for r in rows if all(w in f"{r['id']} {r['name']} {r['vendor']} {r['segment']} {r['backend']}".lower() for w in words)]
    return out[: max(1, min(int(limit), 400))]


def search_models(query: str = "", task: str = "chat", limit: int = 20, request: gr.Request = None) -> list:
    """Search the modelread index of Hugging Face models by name and task (no fit estimate; fast).

    Args:
        query: words that must appear in the repo id, e.g. "qwen3.6" or "gemma 4".
        task: chat | coding | vision | ocr | embedding | speech-to-text | tts | image-generation.
        limit: maximum rows (1-100).
    """
    rows = _get("/api/search", {"q": query, "task": task, "limit": int(limit), "match": bool(query)}, request)
    if not isinstance(rows, list):
        return [rows]
    keep = ("id", "pipeline_tag", "library", "params", "downloads", "likes", "license", "created")
    return [{k: r.get(k) for k in keep} for r in rows]


CSS = ".gradio-container {max-width: 980px !important}"

with gr.Blocks(title="modelread MCP") as demo:
    gr.Markdown(
        "# modelread MCP\n"
        "Will this Hugging Face model run on your hardware, how fast, which quant, and with what command? "
        "This Space is an **MCP server**: add it from [your MCP settings](https://huggingface.co/settings/mcp) "
        f"or use the endpoint below. The full site is [modelread.com]({SITE}).\n\n"
        "MCP endpoint: `https://patrickbdevaney-modelread-mcp.hf.space/gradio_api/mcp/` · "
        f"also available at `{SITE}/mcp`"
    )
    with gr.Tab("Estimate fit"):
        with gr.Row():
            repo = gr.Textbox(label="Repo", value="Qwen/Qwen3.6-27B")
            hw = gr.Textbox(label="Hardware", value="rtx4090")
            ctx = gr.Number(label="Context", value=32768, precision=0)
            kv = gr.Dropdown(["f16", "q8_0", "q4_0"], value="f16", label="KV cache")
        out = gr.JSON(label="Result")
        gr.Button("Estimate", variant="primary").click(estimate_fit, [repo, hw, ctx, kv], out, api_name="estimate_fit")
    with gr.Tab("Compare devices"):
        with gr.Row():
            crepo = gr.Textbox(label="Repo", value="openai/gpt-oss-120b")
            chw = gr.Textbox(label="Devices (comma-separated)", value="rtx5090, m4max-128, dgx-spark, h100-sxm")
            cctx = gr.Number(label="Context", value=32768, precision=0)
        cout = gr.JSON(label="Ranked")
        gr.Button("Compare", variant="primary").click(compare_hardware, [crepo, chw, cctx], cout, api_name="compare_hardware")
    with gr.Tab("Find models"):
        q = gr.Textbox(label="Question", value="best coding model for an RTX 4090 with 64GB RAM at 32k context")
        dh = gr.Textbox(label="Default hardware (if the question names none)", value="")
        fout = gr.JSON(label="Recommendations")
        gr.Button("Find", variant="primary").click(find_models, [q, dh], fout, api_name="find_models")
    with gr.Tab("Hardware"):
        hf_ = gr.Textbox(label="Filter", value="h100")
        hl = gr.Number(label="Limit", value=40, precision=0)
        hout = gr.JSON(label="Devices")
        gr.Button("List").click(list_hardware, [hf_, hl], hout, api_name="list_hardware")
    with gr.Tab("Search"):
        sq = gr.Textbox(label="Query", value="gemma 4")
        st = gr.Dropdown(["chat", "coding", "vision", "ocr", "embedding", "speech-to-text", "tts", "image-generation"], value="chat", label="Task")
        sl = gr.Number(label="Limit", value=20, precision=0)
        sout = gr.JSON(label="Models")
        gr.Button("Search").click(search_models, [sq, st, sl], sout, api_name="search_models")

if __name__ == "__main__":
    demo.launch(mcp_server=True, css=CSS, ssr_mode=False)