modelread-mcp / app.py
patrickbdevaney's picture
Point to modelread.com
4e4180a verified
Raw History Blame Contribute Delete
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)