| --- |
| license: mit |
| tags: |
| - model-family-tree |
| - huggingface |
| - visualization |
| - tools |
| language: |
| - en |
| --- |
| |
| # 🌳 Model Family Tree — Local Desktop App |
|
|
| Automatically traces and visualises the **family tree of any Hugging Face model** in a single self-contained desktop window — no browser or external viewer needed. |
|
|
| Nodes are colour-coded by license type. The tree is interactive: zoom, pan, and hover over any node to see its full model ID. |
|
|
| > ⚠️ **This is a desktop application** (requires Python on your machine). |
| > It is distributed as a code repository, not a Hugging Face Space. |
| > For the original hosted web version, see [mlabonne/model-family-tree](https://huggingface.co/spaces/mlabonne/model-family-tree). |
|
|
| --- |
|
|
| ## Credits |
|
|
| | Contributor | Contribution | |
| |---|---| |
| | Thanks to mlabonne and leonardlin for the original code and adaptation this python app was based on. |
| | [thebrinkster](https://huggingface.co/thebrinkster) | Wrapped original backend code in Tkinter and adapted it to run locally from a Google Colab notebook that can be found (https://colab.research.google.com/drive/1s2eQlolcI1VGgDhqWIANfkfKvcKrMyNr?usp=sharing#scrollTo=lIYdn1woOS1n). |
| | |
| | [mlabonne](https://huggingface.co/mlabonne) | Original concept, core genealogy logic, and the Colab / HF Space this is adapted from | |
| | [leonardlin](https://huggingface.co/leonardlin) | Original caching implementation for model cards | |
| | This repo | Local desktop adaptation — pywebview single-window GUI, vis.js rendering, cross-platform packaging | |
|
|
| **Third-party libraries used:** |
|
|
| | Library | License | Purpose | |
| |---|---|---| |
| | [vis-network](https://github.com/visjs/vis-network) | Apache 2.0 | Interactive tree rendering | |
| | [pywebview](https://github.com/r0x0r/pywebview) | BSD 3-Clause | Native desktop window (Edge/WebKit) | |
| | [networkx](https://github.com/networkx/networkx) | BSD 3-Clause | Graph construction | |
| | [huggingface_hub](https://github.com/huggingface/huggingface_hub) | Apache 2.0 | Model card fetching | |
| | [requests](https://github.com/psf/requests) | Apache 2.0 | HTTP requests for merge YAML files | |
|
|
| --- |
|
|
| ## Prerequisites |
|
|
| - Python 3.8+ |
| - `pip` (comes with Python) |
| - Internet connection (to fetch model cards from Hugging Face) |
|
|
| **Platform support:** |
|
|
| | OS | Web engine used | Extra install? | |
| |---|---|---| |
| | Windows 10/11 | Edge WebView2 (built-in) | None | |
| | macOS | WKWebView (built-in) | None | |
| | Linux | GTK WebKit2 | `sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-webkit2-4.0` | |
|
|
| --- |
|
|
| ## Setup (one time only) |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| --- |
|
|
| ## Running |
|
|
| ```bash |
| python model_tree.py |
| ``` |
|
|
| A single desktop window opens with everything inside it: |
|
|
| | Area | Purpose | |
| |---|---| |
| | **Top bar** | Model ID input field + Generate button | |
| | **Left panel** | Live log — shows each model as it's fetched | |
| | **Main canvas** | Interactive vis.js family tree | |
| | **Status bar** | Shows idle / running / done / error state | |
|
|
| ### Steps |
| 1. Type a Hugging Face model ID into the input box (e.g. `mistralai/Mistral-7B-v0.1`) |
| 2. Click **Generate ▶** or press **Enter** |
| 3. Watch the log panel as models are fetched |
| 4. The tree appears in the main canvas when complete — zoom, pan, click nodes freely |
| 5. Clear the input, type a new model, and generate again any time |
|
|
| --- |
|
|
| ## Legend |
|
|
| | Colour | Meaning | |
| |---|---| |
| | 🟢 Green | Permissive license (MIT, BSD, Apache-2.0, OpenRAIL) | |
| | 🔴 Red/Coral | Noncommercial or restrictive license | |
| | ⬜ Gray | License unknown or model card not found | |
|
|
| --- |
|
|
| ## Tips |
|
|
| - Large trees can take a minute or two — watch the live log. |
| - The cache is cleared automatically on each new Generate run. |
| - The default model ID can be changed by editing `DEFAULT_MODEL_ID` at the top of `model_tree.py`. |
|
|
| --- |
|
|
| ## License |
|
|
| MIT — see [LICENSE](./LICENSE) for full text and third-party attributions. |
|
|
