Spaces:
Running
Running
Download app.py from patrickbdevaney/modelread-mcp: direct link, hf CLI and curl.
- Browser
- Download file 11.1 kB
-
https://huggingface.co/spaces/patrickbdevaney/modelread-mcp/resolve/main/app.py
- Command line
-
hf download hf://spaces/patrickbdevaney/modelread-mcp/app.py
-
curl -L -o app.py https://huggingface.co/spaces/patrickbdevaney/modelread-mcp/resolve/main/app.py
11.1 kB
| """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) | |