ai-model-explorer 0.1.0__py3-none-any.whl

ai_model_explorer/__init__.py

@@ -0,0 +1,13 @@
+"""AI Model Explorer: see any AI model's architecture from its weight manifest, without downloading the weights.
+
+    from ai_model_explorer import inspect, summary
+    a = inspect("Qwen/Qwen3-8B")
+    print(summary(a))
+
+Method: S. Singkul, "Reading the Architecture off the Weights: Manifest-Only Recovery of Neural Network Anatomy", 2026.
+"""
+__version__ = "0.1.0"
+
+from .api import inspect, summary  # noqa: E402
+
+__all__ = ["inspect", "summary", "__version__"]

ai_model_explorer/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

ai_model_explorer/_engine.py

@@ -0,0 +1,100 @@
+"""Run the explorer's own JavaScript (loaders.js, infer.js) inside QuickJS, so Python gets exactly the website's result.
+
+Python does the network I/O: the JS side calls a small fetch() shim that hands each request to Python. Binary bodies
+cross the boundary as latin-1 strings (one char per byte), which QuickJS turns back into a Uint8Array.
+"""
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Callable, Optional
+
+try:
+    import quickjs  # type: ignore
+except ImportError as e:  # pragma: no cover
+    raise ImportError("ai-model-explorer needs the 'quickjs' package: pip install quickjs") from e
+
+_PRELUDE = r"""
+var window = undefined;
+function TextDecoder() {}
+TextDecoder.prototype.decode = function (u8) {
+  if (!u8) return "";
+  var src = u8.buffer && u8.buffer.__s;
+  if (src !== undefined && u8.byteOffset === 0 && u8.length === u8.buffer.byteLength) return __pyutf8(src);
+  var CH = 0x8000, parts = [];
+  for (var i = 0; i < u8.length; i += CH) parts.push(String.fromCharCode.apply(null, u8.subarray(i, i + CH)));
+  var s = parts.join("");
+  try { return decodeURIComponent(escape(s)); } catch (e) { return s; }
+};
+function __bytes(s) { var u = new Uint8Array(s.length); for (var i = 0; i < s.length; i++) u[i] = s.charCodeAt(i) & 255; return u; }
+function fetch(url, opts) {
+  var range = opts && opts.headers && opts.headers.Range ? opts.headers.Range : "";
+  var r = JSON.parse(__pyfetch(url, range));
+  var body = r.body;
+  return Promise.resolve({
+    status: r.status, ok: r.status >= 200 && r.status < 300,
+    text: function () { return Promise.resolve(new TextDecoder().decode(__bytes(body))); },
+    json: function () { return Promise.resolve(JSON.parse(new TextDecoder().decode(__bytes(body)))); },
+    arrayBuffer: function () { var b = __bytes(body).buffer; b.__s = body; return Promise.resolve(b); }
+  });
+}
+var module = undefined;
+"""
+
+
+def _js(name: str) -> str:
+    return resources.files("ai_model_explorer").joinpath("js", name).read_text(encoding="utf-8")
+
+
+class Engine:
+    def __init__(self, fetch: Optional[Callable[[str, str], tuple]] = None):
+        self.ctx = quickjs.Context()
+        self.ctx.set_max_stack_size(8 * 1024 * 1024)
+        self._fetch = fetch
+        self.ctx.add_callable("__pyfetch", self._pyfetch)
+        self.ctx.add_callable("__pyget", self._pyget)
+        self.ctx.add_callable("__pyutf8", lambda s: s.encode("latin-1").decode("utf-8", "replace"))
+        self._inbox = {}
+        self.ctx.eval(_PRELUDE)
+        self.ctx.eval(_js("loaders.js"))
+        self.ctx.eval(_js("infer.js"))
+
+    # ---- host callbacks
+    def _pyfetch(self, url, rng):
+        if self._fetch is None:
+            return json.dumps({"status": 599, "body": ""})
+        status, body = self._fetch(url, rng or None)
+        return json.dumps({"status": status, "body": body.decode("latin-1")})
+
+    def _pyget(self, key):
+        return self._inbox.pop(key)
+
+    def _put(self, key, obj) -> str:
+        self._inbox[key] = json.dumps(obj)
+        return f'JSON.parse(__pyget("{key}"))'
+
+    def _await(self, expr: str):
+        """Evaluate an async JS expression to completion and return its JSON value."""
+        self.ctx.eval(
+            "var __res = undefined, __err = undefined;"
+            f"Promise.resolve({expr}).then(function (v) {{ __res = JSON.stringify(v === undefined ? null : v); }},"
+            " function (e) { __err = String(e && e.message || e); });")
+        while self.ctx.execute_pending_job():
+            pass
+        err = self.ctx.eval("__err")
+        if err is not None:
+            raise RuntimeError(err)
+        res = self.ctx.eval("__res")
+        if res is None:
+            raise RuntimeError("JavaScript promise did not settle")
+        return json.loads(res)
+
+    # ---- API
+    def hf_manifest(self, repo: str, files: list, opt: dict):
+        return self._await(f'Loaders.hfManifest({json.dumps(repo)}, {self._put("files", files)}, function () {{}}, {self._put("opt", opt)})')
+
+    def infer(self, tensors: dict, lex: bool = True) -> dict:
+        return self._await(f'ArchInfer.infer({self._put("t", tensors)}, {{lex: {"true" if lex else "false"}}})')
+
+    def fuse(self, anatomy: dict, config: dict):
+        return self._await(f'ArchInfer.fuseConfig({self._put("a", anatomy)}, {self._put("c", config)})')

ai_model_explorer/_hub.py

@@ -0,0 +1,50 @@
+"""Minimal HTTP for Hugging Face: file list, small JSON files, and byte ranges. Standard library only."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from typing import Optional
+
+from . import __version__
+
+ENDPOINT = os.environ.get("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
+
+
+class Hub:
+    def __init__(self, token: Optional[str] = None, timeout: float = 60.0):
+        self.token = token or os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        self.timeout = timeout
+        self.bytes_read = 0
+
+    def get(self, url: str, rng: Optional[str] = None):
+        """Return (status, body bytes). Never raises for HTTP errors; the caller decides."""
+        url = url.replace("https://huggingface.co", ENDPOINT, 1)
+        h = {"User-Agent": f"ai-model-explorer/{__version__}"}
+        if rng:
+            h["Range"] = rng
+        if self.token and url.startswith(ENDPOINT):
+            h["Authorization"] = f"Bearer {self.token}"
+        try:
+            with urllib.request.urlopen(urllib.request.Request(url, headers=h), timeout=self.timeout) as r:
+                body = r.read()
+                self.bytes_read += len(body)
+                return r.status, body
+        except urllib.error.HTTPError as e:
+            return e.code, e.read() or b""
+
+    def json(self, url: str):
+        st, body = self.get(url)
+        if st in (401, 403):
+            raise PermissionError("gated or private repository: accept its license on Hugging Face and pass a token (HF_TOKEN)")
+        if st == 404:
+            m = re.search(r"/api/models/([^?]+)", url)
+            raise FileNotFoundError(f"repository not found: {m.group(1)}" if m else f"not found: {url}")
+        if st >= 400:
+            raise RuntimeError(f"HTTP {st} for {url}")
+        return json.loads(body.decode("utf-8"))
+
+    def model_info(self, repo: str) -> dict:
+        return self.json(f"https://huggingface.co/api/models/{repo}?blobs=true")

ai_model_explorer/api.py

@@ -0,0 +1,166 @@
+"""inspect(): the anatomy of a model from its weight manifest, for a Hugging Face repo or local safetensors files."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import struct
+from pathlib import Path
+from typing import Optional, Union
+
+from ._engine import Engine
+from ._hub import Hub
+
+
+def _local_header(path: Path) -> tuple[dict, int]:
+    with open(path, "rb") as f:
+        n = struct.unpack("<Q", f.read(8))[0]
+        if not 0 < n < 200_000_000:
+            raise ValueError(f"{path} is not a safetensors file")
+        h = json.loads(f.read(n).decode("utf-8"))
+    h.pop("__metadata__", None)
+    return h, 8 + n
+
+
+def _local(path: Path):
+    files = [path] if path.is_file() else sorted(p for p in path.rglob("*.safetensors") if not re.search(r"(^|/)(optimizer|adapter[._])", str(p)))
+    if not files:
+        raise FileNotFoundError(f"no .safetensors file under {path}")
+    tensors, read = {}, 0
+    base = path if path.is_dir() else path.parent
+    for p in files:
+        h, b = _local_header(p)
+        read += b
+        rel = p.relative_to(base).parent.as_posix()
+        prefix = "" if rel in ("", ".") else rel.replace("/", ".") + "."
+        for k, v in h.items():
+            tensors[prefix + k] = {"dtype": v["dtype"], "shape": v["shape"]}
+    cfg = None
+    c = base / "config.json"
+    if c.exists():
+        cfg = json.loads(c.read_text(encoding="utf-8"))
+    return tensors, cfg, read, len(files), None
+
+
+def _remote(repo: str, hub: Hub):
+    info = hub.model_info(repo)
+    files = [{"n": s["rfilename"], "size": s.get("size") or 0} for s in info.get("siblings", [])]
+    names = {f["n"] for f in files}
+    base = f"https://huggingface.co/{repo}/resolve/main/"
+    cfg = mi = None
+    if "config.json" in names:
+        try:
+            cfg = hub.json(base + "config.json")
+        except Exception:
+            cfg = None
+    if "model_index.json" in names:
+        try:
+            mi = hub.json(base + "model_index.json")
+        except Exception:
+            mi = None
+    opt = {"prefer": (cfg or {}).get("default_size"),
+           "only": [k for k, v in (mi or {}).items() if not k.startswith("_") and isinstance(v, list) and v and v[0]] if mi else None}
+    eng = Engine(fetch=hub.get)
+    mf = eng.hf_manifest(repo, files, opt)
+    if not mf:
+        raise FileNotFoundError(f"{repo}: no .safetensors or PyTorch checkpoint found")
+    weight_bytes = sum(f["size"] for f in files)
+    return mf["tensors"], cfg, mf["read"], mf["nfiles"], {"engine": eng, "weight_bytes": weight_bytes,
+                                                         "downloads": info.get("downloads"), "hub_params": (info.get("safetensors") or {}).get("total")}
+
+
+def inspect(model: Union[str, os.PathLike], token: Optional[str] = None, config: Optional[dict] = None,
+            include_tensors: bool = False) -> dict:
+    """Recover a model's anatomy without downloading its weights.
+
+    model:  a Hugging Face repo id ("Qwen/Qwen3-8B", or a huggingface.co URL), a .safetensors file, or a folder of them.
+    token:  Hugging Face token for gated or private repos (default: $HF_TOKEN).
+    config: a config.json dict to fuse instead of the repo's own.
+    Returns a JSON-serializable dict: family, totals, hyperparameters, components with their layer stacks and block
+    types, edges between components, quantization, the config check, and how many bytes were read.
+    """
+    s = str(model)
+    if os.path.exists(s):
+        tensors, cfg, read, nfiles, extra = _local(Path(s))
+        eng = Engine()
+        source = {"kind": "local", "path": str(Path(s).resolve())}
+    else:
+        m = re.search(r"(?:huggingface\.co/)?([\w.-]+/[\w.-]+)", s)
+        if not m:
+            raise ValueError("expected a Hugging Face repo id (owner/name) or a path to .safetensors")
+        repo = re.sub(r"/(tree|blob|resolve)/.*$", "", m.group(1))
+        tensors, cfg, read, nfiles, extra = _remote(repo, Hub(token))
+        eng = extra.pop("engine")
+        source = {"kind": "huggingface", "repo": repo, **{k: v for k, v in extra.items() if v is not None}}
+    if config is not None:
+        cfg = config
+    anatomy = eng.infer(tensors)
+    check = eng.fuse(anatomy, cfg) if cfg else None
+    out = {
+        "source": source,
+        "files_read": nfiles,
+        "header_bytes": read,
+        "tensor_count": len(tensors),
+        "family": anatomy.get("family"),
+        "totals": anatomy.get("totals"),
+        "hyperparameters": anatomy.get("hp"),
+        "quantization": anatomy.get("quant"),
+        "components": anatomy.get("comps"),
+        "edges": anatomy.get("edges"),
+        "evidence": anatomy.get("evidence"),
+        "config_check": check,
+        "has_config": cfg is not None,
+    }
+    if include_tensors:
+        out["tensors"] = anatomy.get("tensors")
+    return out
+
+
+def _fmt_n(n) -> str:
+    if n is None:
+        return "?"
+    for u, k in (("T", 1e12), ("B", 1e9), ("M", 1e6), ("K", 1e3)):
+        if n >= k:
+            return f"{n / k:.2f}{u}".replace(".00", "")
+    return str(n)
+
+
+def _fmt_b(n) -> str:
+    if n is None:
+        return "?"
+    for u, k in (("TB", 1e12), ("GB", 1e9), ("MB", 1e6), ("KB", 1e3)):
+        if n >= k:
+            return f"{n / k:.1f} {u}"
+    return f"{n} B"
+
+
+def summary(a: dict) -> str:
+    """A short human-readable report of an inspect() result."""
+    src = a["source"]
+    name = src.get("repo") or src.get("path")
+    t = a.get("totals") or {}
+    hp = a.get("hyperparameters") or {}
+    lines = [f"{name}",
+             f"  family {a.get('family')} · {_fmt_n(t.get('params'))} parameters · {_fmt_b(t.get('bytes'))} of weights"
+             + (f" · stored as {', '.join(a['quantization'])}" if a.get("quantization") else ""),
+             f"  read {_fmt_b(a.get('header_bytes'))} from {a.get('files_read')} file(s), {a.get('tensor_count')} tensors"]
+    keys = [("d", "width"), ("layers", "layers"), ("heads", "heads"), ("kv_heads", "kv heads"), ("head_dim", "head dim"),
+            ("ffn", "ffn"), ("experts", "experts"), ("vocab", "vocab")]
+    hps = " · ".join(f"{lab} {hp[k]}" for k, lab in keys if hp.get(k))
+    if hps:
+        lines.append("  " + hps)
+    lines.append("  components:")
+    for c in a.get("components") or []:
+        role = c.get("role") or ""
+        head = f"    {c.get('id')}" + (f" ({role})" if role else "") + (f" · d={c['d']}" if c.get("d") else "")
+        lines.append(head)
+        for st in c.get("stacks") or []:
+            types = ", ".join(f"{ty.get('label')}" + (f" ×{ty['n']}" if ty.get("n") and len(st.get("types", [])) > 1 else "") for ty in st.get("types") or [])
+            lines.append(f"      {st.get('path')}: {st.get('n')} blocks · {types}")
+    for e in a.get("edges") or []:
+        lines.append(f"    {e.get('from')} → {e.get('to')}" + (f" (via {e['via']})" if e.get("via") else ""))
+    chk = a.get("config_check")
+    if chk:
+        bad = [k for k, v in chk.items() if isinstance(v, dict) and v.get("checked") and v.get("consistent") is False]
+        lines.append("  config.json: " + ("agrees with the weights" if not bad else "disagrees with the weights for " + ", ".join(bad)))
+    return "\n".join(lines)

ai_model_explorer/cli.py

@@ -0,0 +1,75 @@
+"""Command line: `ai-model-explorer open [REPO]` starts the web app locally; `ai-model-explorer inspect REPO` prints the anatomy."""
+from __future__ import annotations
+
+import argparse
+import functools
+import http.server
+import json
+import socketserver
+import sys
+import threading
+import urllib.parse
+import webbrowser
+from importlib import resources
+
+from . import __version__
+
+
+def _serve(repo: str | None, port: int, lang: str, no_browser: bool) -> None:
+    web = resources.files("ai_model_explorer").joinpath("web")
+    with resources.as_file(web) as root:
+        handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=str(root))
+        handler.log_message = lambda *a, **k: None
+        with socketserver.TCPServer(("127.0.0.1", port), handler) as httpd:
+            url = f"http://127.0.0.1:{httpd.server_address[1]}/" + ("en/" if lang == "en" else "")
+            if repo:
+                url += "#hf=" + urllib.parse.quote(repo, safe="/")
+            print(f"AI Model Explorer {__version__} running at {url}  (Ctrl+C to stop)")
+            if not no_browser:
+                threading.Timer(0.4, lambda: webbrowser.open(url)).start()
+            try:
+                httpd.serve_forever()
+            except KeyboardInterrupt:
+                print()
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="ai-model-explorer",
+                                description="See any AI model's architecture from its safetensors header, without downloading weights.")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    o = sub.add_parser("open", help="open the web app in your browser (runs locally, works offline for files)")
+    o.add_argument("repo", nargs="?", help="Hugging Face repo to load right away, e.g. Qwen/Qwen3-8B")
+    o.add_argument("--port", type=int, default=0, help="port (default: any free port)")
+    o.add_argument("--lang", choices=["th", "en"], default="en")
+    o.add_argument("--no-browser", action="store_true", help="only print the URL")
+
+    i = sub.add_parser("inspect", help="print the anatomy of a Hugging Face repo or local .safetensors")
+    i.add_argument("model", help="repo id (owner/name), huggingface.co URL, .safetensors file or folder")
+    i.add_argument("--json", action="store_true", help="print the full result as JSON")
+    i.add_argument("--tensors", action="store_true", help="with --json: include the role of every tensor")
+    i.add_argument("--token", help="Hugging Face token for gated/private repos (default: $HF_TOKEN)")
+    i.add_argument("--config", help="path to a config.json to use instead of the repo's own")
+
+    a = p.parse_args(argv)
+    if a.cmd in (None, "open"):
+        _serve(getattr(a, "repo", None), getattr(a, "port", 0), getattr(a, "lang", "en"), getattr(a, "no_browser", False))
+        return 0
+
+    from .api import inspect, summary
+    cfg = None
+    if a.config:
+        with open(a.config, encoding="utf-8") as f:
+            cfg = json.load(f)
+    try:
+        r = inspect(a.model, token=a.token, config=cfg, include_tensors=a.tensors)
+    except (PermissionError, FileNotFoundError, ValueError, RuntimeError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(json.dumps(r, indent=1, ensure_ascii=False) if a.json else summary(r))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())