Spaces:
Running
Running
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)
|