model-cards

CLI reference tool for open-weight AI models. Search, inspect, and compare Hugging Face model cards — all from your terminal.

Why?

The open-weight AI model landscape is exploding. Every week brings a new release — Qwen, DeepSeek, Llama, Mistral, Phi, Gemma, and more. Keeping track of their specs (parameters, context window, license, architecture, hardware requirements) across scattered Hugging Face pages is tedious.

model-cards solves this by bringing the Hugging Face model registry to your terminal. One command to search, one to inspect details, one to compare models side-by-side. No browser tabs, no clicking around — just structured specs at your fingertips.

Installation

From PyPI

pip install model-cards

From source

git clone https://github.com/your-username/model-cards.git
cd model-cards
pip install -e .

# For development (includes pytest):
pip install -e ".[dev]"

Usage

`search` — Find models by keyword

model-cards search qwen

Outputs a rich terminal table with results sorted by download count:

┌────────────────────────────────────────────────────────────┐
│               Search Results: qwen                         │
├──────────────────────────────┬────────┬──────────┬────────┤
│ Model ID                     │ Task   │ Downloads│  Likes │
├──────────────────────────────┼────────┼──────────┼────────┤
│ Qwen/Qwen2.5-7B-Instruct    │ text-  │   18.5M  │  12.3K │
│                              │ gener. │          │        │
│ Qwen/Qwen2.5-32B-Instruct   │ text-  │    3.2M  │   3.1K │
│                              │ gener. │          │        │
│ Qwen/Qwen3-8B                │ text-  │    1.8M  │   2.8K │
│                              │ gener. │          │        │
└──────────────────────────────┴────────┴──────────┴────────┘

Limit results

model-cards search llama --limit 20

Controls how many results to return (default: 10, max: 50).

`show` — Inspect a single model in detail

model-cards show Qwen/Qwen2.5-7B-Instruct

Renders a detailed information panel:

╭─────────────────────── Model Details ───────────────────────╮
│                                                              │
│  Overview                                                    │
│    Model ID:    Qwen/Qwen2.5-7B-Instruct                     │
│    Task:        text-generation                               │
│    License:     apache-2.0                                    │
│    Created:     2024-09-18                                    │
│    Visibility:  Public                                        │
│                                                              │
│  Hardware                                                    │
│    Parameters:              7.6B                              │
│    Recommended Hardware:    Moderate (<=16GB) (~15.2 GB VRAM)│
│                                                              │
│  Specs                                                       │
│    Context Window:          32K                               │
│    Architecture:            Qwen2ForCausalLM                  │
│    Precision:               bfloat16                          │
│    Framework:               transformers                      │
│                                                              │
│  Benchmarks                                                  │
│    - MMLU:         85.4                                      │
│    - GSM8K:        92.0                                      │
│                                                              │
│  Card Metadata                                               │
│    Datasets:   [datasets list]                                │
│    Languages:  en, zh                                        │
│    Base Model: N/A                                           │
│    CO2 Emissions: N/A                                        │
│                                                              │
│  Stats                                                       │
│    Downloads:  18.5M                                         │
│    Likes:      12.3K                                         │
╰──────────────────────────────────────────────────────────────╯

`compare` — Side-by-side model comparison

model-cards compare qwen3-coder kimi-k2.6 deepseek-v4

Displays a comparison table with the best value in each row highlighted in bold green:

┌──────────────────┬──────────────────┬──────────────────┬──────────────────┐
│ Field            │ qwen3-coder      │ kimi-k2.6        │ deepseek-v4      │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Task             │ text-generation  │ text-generation  │ text-generation  │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Parameters       │ 8.2B             │ 2.6B             │ 30.0B ▲          │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Context Window   │ 128K ▲           │ 128K ▲           │ 128K ▲           │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ License          │ apache-2.0       │ mit              │ custom           │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Downloads        │ 1.2M             │ 890.5K           │ 4.3M ▲           │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Likes            │ 1.8K             │ 2.1K ▲           │ 1.5K             │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Hardware Rating  │ Moderate         │ Easy ▲           │ Very Heavy       │
└──────────────────┴──────────────────┴──────────────────┴──────────────────┘

Supports 2–4 models per comparison. The ▲ marker indicates the best performer in each numeric row.

`list` — Trending open-weight models

model-cards list

Fetches a curated list of trending open-weight models (Qwen, DeepSeek, Llama, Mistral, and more) from the Hugging Face API, sorted by download popularity:

┌──────────────────────────────────────────────────────────────────┐
│              Trending Open-Weight Models (fetched from API)       │
├────────────────────────────────┬────────────────┬────────┬───────┤
│ Model ID                       │ Task           │ Downl. │ Likes │
├────────────────────────────────┼────────────────┼────────┼───────┤
│ Qwen/Qwen2.5-7B-Instruct      │ text-generation│ 18.5M  │ 12.3K │
│ deepseek-ai/DeepSeek-R1...     │ text-generation│ 15.2M  │  9.1K │
│ meta-llama/Llama-3.1-8B-Instr.│ text-generation│ 12.8M  │  8.5K │
│ ...                            │                │        │       │
└────────────────────────────────┴────────────────┴────────┴───────┘

`--json` flag — Pipeline-friendly output

Every command supports --json for integration into scripts and pipelines:

model-cards search qwen --json | jq '.[].model_id'
model-cards show Qwen/Qwen2.5-7B-Instruct --json > model.json
model-cards compare qwen3-coder kimi-k2.6 --json | jq .
model-cards list --json

Displayed Fields

Field	Description	`search` / `list`	`show`	`compare`
Model ID	Full Hugging Face model identifier	✅	✅	✅
Task	Pipeline tag (e.g., text-generation)	✅	✅	✅
Parameters	Parameter count (M/B notation)	—	✅	✅
Context Window	Maximum sequence length (K notation)	—	✅	✅
License	Model license (apache-2.0, mit, etc.)	✅	✅	✅
Architecture	Model architecture class	—	✅	—
Hardware	Estimated RAM requirement & rating	—	✅	✅
Downloads	Total download count	✅	✅	✅
Likes	Heart/like count on Hugging Face	✅	✅	✅
Benchmarks	Reported benchmark scores (MMLU, GSM8K...)	—	✅	—
Precision	Weight dtype (bfloat16, int8, etc.)	—	✅	—
Last Updated	Last modification date	✅	—	—

Environment Variables

Variable	Required	Description
`HF_TOKEN`	No	Hugging Face access token. Set this for authenticated requests — unlocks higher API rate limits from Hugging Face.

export HF_TOKEN=hf_your_token_here

Tech Stack & Architecture

model-cards/
├── model_cards/
│   ├── cli.py         # argparse entry point
│   ├── api.py         # Hugging Face API client + data normalization
│   ├── display.py     # Rich table / panel rendering
│   └── compare.py     # Side-by-side comparison table
├── tests/
│   └── test_model_cards.py
├── pyproject.toml
└── README.md

Components

CLI (cli.py) — Built with argparse (zero extra dependencies). Exposes search, show, compare, and list subcommands. Each dispatches to the async API client via asyncio.run().
API Client (api.py) — An httpx.AsyncClient-based client that talks to https://huggingface.co/api/models. Features:
- Async architecture: Concurrent model fetches via asyncio.gather() for speed.
- Rate limiting: Enforces 1 request/second by default (Hugging Face free-tier friendly).
- In-memory caching: Deduplicates repeated requests within a CLI session.
- Data normalization: Extracts and normalizes fields from the raw Hugging Face API response — parameters, context window, architecture, precision, benchmarks, and hardware estimates.
Display (display.py) — Uses rich for terminal output:
- render_models_table() — Tabular output for search and list commands.
- render_model_panel() — Detailed rich.panel.Panel for model inspection.
- print_json() — Structured JSON output for pipelines.
Comparison (compare.py) — build_comparison_table() generates a side-by-side rich.table.Table with automatic highlighting of the best value per row (bold green).

Data Normalization

The API client normalizes raw Hugging Face payloads into a clean schema:

Parameters — Extracted from cardData.metadata, config.json, or estimated from .safetensors file sizes (2 bytes/param approximation).
Context Window — Resolved from metadata.max_length, config.max_position_embeddings, or fallback fields.
Architecture — Parsed from config.architectures[0] or config.model_type.
Hardware Estimate — RAM required for inference, calculated from parameter count × precision bytes (with 20% overhead). Categorized as Easy (≤8 GB), Moderate (≤16 GB), Heavy (≤24 GB), or Very Heavy.
Benchmarks — Metric values from cardData.metrics.

License

MIT — see LICENSE for details.

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Development setup

git clone https://github.com/your-username/model-cards.git
cd model-cards
pip install -e ".[dev]"
pytest

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
model_cards.egg-info		model_cards.egg-info
model_cards		model_cards
tests		tests
README.md		README.md
SPEC.md		SPEC.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

model-cards

Why?

Installation

From PyPI

From source

Usage

`search` — Find models by keyword

Limit results

`show` — Inspect a single model in detail

`compare` — Side-by-side model comparison

`list` — Trending open-weight models

`--json` flag — Pipeline-friendly output

Displayed Fields

Environment Variables

Tech Stack & Architecture

Components

Data Normalization

License

Contributing

Development setup

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

model-cards

Why?

Installation

From PyPI

From source

Usage

search — Find models by keyword

Limit results

show — Inspect a single model in detail

compare — Side-by-side model comparison

list — Trending open-weight models

--json flag — Pipeline-friendly output

Displayed Fields

Environment Variables

Tech Stack & Architecture

Components

Data Normalization

License

Contributing

Development setup

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`search` — Find models by keyword

`show` — Inspect a single model in detail

`compare` — Side-by-side model comparison

`list` — Trending open-weight models

`--json` flag — Pipeline-friendly output