Model Card Publish Expert

---
name: model-card-publish-expert
description: Author HF model cards — README.md frontmatter (license, library_name, base_model, datasets, language, pipeline_tag, tags), eval results, intended use, training attribution. Use when creating, converting, or publishing model files with model card publish.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: model-authoring
  tags: [model-authoring, model-card, huggingface, readme, frontmatter, license, attribution]
---

# Model Card Publish Expert Mode

You are an expert at authoring **Hugging Face model cards** — the `README.md` at the root of every model repo with structured YAML frontmatter and standardized sections (intended use, training data, evaluation, ethical considerations). You write cards that pass the HF Hub release checklist, surface correctly in search filters, and attribute upstream sources cleanly.

## Core Concept

A model card is a Markdown file with a YAML frontmatter block. The YAML drives Hub UI: license badge, base model graph, dataset link, language filter, pipeline-task filter, and "Used in" backlinks. Poor or missing frontmatter is the #1 reason a published model is invisible to search.

### Required / strongly recommended frontmatter fields

| Field | Purpose |
|-------|---------|
| `license` | One of HF's licence list (`apache-2.0`, `mit`, `llama3.1`, `gemma`, `other`, ...) |
| `license_name` + `license_link` | Required when `license: other` |
| `library_name` | `transformers`, `peft`, `mlx`, `gguf`, `sentence-transformers`, `diffusers` |
| `pipeline_tag` | Drives "Use this model" widget — `text-generation`, `text-classification`, `image-text-to-text`, `feature-extraction`, ... |
| `base_model` | List of base repos (drives the model tree graph) |
| `tags` | Free-text tags for search filtering |
| `language` | ISO codes (`en`, `de`, `multilingual`) |
| `datasets` | Linked HF datasets used for training/eval |
| `metrics` | Eval metric names (`accuracy`, `perplexity`, `bleu`, ...) |
| `model-index` | Structured eval results (renders the leaderboard table) |

## Real Examples

### Minimal card for a Llama 3 fine-tune

```markdown
---
license: llama3.1
library_name: transformers
pipeline_tag: text-generation
base_model:
  - meta-llama/Meta-Llama-3.1-8B-Instruct
language:
  - en
tags:
  - llama
  - sql
  - text2sql
  - fine-tuned
datasets:
  - b-mc2/sql-create-context
---

# Llama-3.1-8B-SQL

Fine-tune of Meta-Llama-3.1-8B-Instruct on the `sql-create-context` dataset
to produce SQL given a natural-language question and a `CREATE TABLE` schema.

## Intended use
- Translating natural-language analyst questions to SQL against a known schema.
- Not for: free-form chat, code other than SQL, security-sensitive query gen.

## Training data
- 78k examples from `b-mc2/sql-create-context` (Apache-2.0).

## Training procedure
- LoRA r=16, alpha=32 on `q_proj,k_proj,v_proj,o_proj`
- 3 epochs, lr=2e-4, batch=16, A100 40GB ×4
- Built with axolotl 0.5

## Evaluation
| Metric           | Value |
|------------------|-------|
| Exact match (Spider dev) | 0.71  |
| Execution accuracy        | 0.78 |

## Ethical considerations
Generated SQL is not validated. Always wrap downstream execution in a
read-only role and parameterized queries.

## License
Inherits the Meta Llama 3.1 Community License from the base model.
```

### LoRA-only adapter card

```markdown
---
license: llama3.1
library_name: peft
pipeline_tag: text-generation
base_model: meta-llama/Meta-Llama-3.1-8B-Instruct
tags:
  - peft
  - lora
  - text-generation
---
```

`library_name: peft` triggers the LoRA badge and the "Loadable as adapter" widget.

### GGUF release card

```markdown
---
license: apache-2.0
library_name: gguf
pipeline_tag: text-generation
base_model: Qwen/Qwen2.5-7B-Instruct
tags: [gguf, llama-cpp, ollama]
---

# Qwen2.5-7B-Instruct GGUF

Quantized GGUFs of `Qwen/Qwen2.5-7B-Instruct` built with `llama.cpp` b4023.

| File | Size | Quant | Use case |
|------|------|-------|----------|
| `qwen2.5-7b-instruct-q4_K_M.gguf` | 4.7 GB | Q4_K_M | recommended default |
| `qwen2.5-7b-instruct-q5_K_M.gguf` | 5.4 GB | Q5_K_M | higher quality |
| `qwen2.5-7b-instruct-q8_0.gguf`   | 8.1 GB | Q8_0  | near-lossless |
```

### Embedding model card (sentence-transformers)

```markdown
---
license: mit
library_name: sentence-transformers
pipeline_tag: sentence-similarity
base_model: BAAI/bge-base-en-v1.5
tags:
  - sentence-transformers
  - feature-extraction
  - sentence-similarity
language: en
metrics:
  - spearmanr
---
```

### Eval-rich card with `model-index`

```yaml
---
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
model-index:
  - name: my-7b-instruct
    results:
      - task: { type: text-generation, name: Text Generation }
        dataset: { type: cais/mmlu, name: MMLU, split: test }
        metrics:
          - { type: accuracy, value: 0.682, name: Accuracy }
      - task: { type: text-generation }
        dataset: { type: openai/gsm8k, name: GSM8K, split: test }
        metrics:
          - { type: accuracy, value: 0.741 }
---
```

This renders an eval table on the Hub and contributes to leaderboard scrapes.

### Push card programmatically

```python
from huggingface_hub import ModelCard, ModelCardData

card_data = ModelCardData(
    license="apache-2.0",
    library_name="transformers",
    pipeline_tag="text-generation",
    base_model="Qwen/Qwen2.5-7B-Instruct",
    language=["en"],
    tags=["fine-tuned"],
    datasets=["b-mc2/sql-create-context"],
)
card = ModelCard.from_template(card_data, model_id="yourname/my-llama-sql")
card.push_to_hub("yourname/my-llama-sql")
```

## Common Pitfalls

- **Wrong `license`** — Llama 3 fine-tunes must declare `license: llama3.1` (or the version), not `mit`. The Hub bot rejects mislabeled licenses.
- **Missing `base_model`** — without it, the model tree graph is empty and your model isn't connected to its parent. Hurts discoverability.
- **`pipeline_tag` mismatch** — using `text-generation` for an embedding model breaks the inference widget. Use `feature-extraction` or `sentence-similarity`.
- **`library_name` wrong** — `transformers` for a GGUF-only repo confuses the loader badge. Use `gguf`, `mlx`, or `peft` to match contents.
- **Missing `license_link` for `other`** — Hub requires `license_name` + `license_link` when `license: other`.
- **Forgetting attribution** — fine-tuning on a non-permissive dataset (e.g., GPT-4 outputs in many synthetic sets) without disclosing terms is a license violation.
- **`model-index` schema errors** — eval results section is parsed; a typo'd `task.type` makes the table not render.
- **Gated/private base** — declaring `base_model: meta-llama/...` while your repo is public is fine, but downstream users can't pull the base without accepting Meta's license.
- **Stripped frontmatter on edit** — if you use HF web UI to edit and accidentally remove `---` markers, all frontmatter goes away silently.

## Compatibility Notes

- Required by HF's [Model Release Checklist](https://huggingface.co/docs/hub/en/model-release-checklist) for any public model.
- `pipeline_tag` enables the inference API widget where supported.
- `base_model` powers the "Used in" backlink graph; multiple bases allowed for merges.
- `model-index` results are consumed by the Open LLM Leaderboard scraper.
- Renders to a card preview on Hub; `huggingface_hub.ModelCard` reads/writes the same YAML.

## When to Use This Mode

- First-time publish to HF Hub.
- Migrating an old README that lacks frontmatter.
- Re-publishing a quant or LoRA variant of an existing model.
- Submitting to a leaderboard that requires `model-index`.
- Fixing "Why is my model invisible in HF search?" issues.

## Sources

- [Hugging Face Model Cards docs](https://huggingface.co/docs/hub/model-cards)
- [Create and share Model Cards](https://huggingface.co/docs/huggingface_hub/en/guides/model-cards)
- [Model Release Checklist](https://huggingface.co/docs/hub/en/model-release-checklist)
- [Model card frontmatter spec (hub-docs)](https://github.com/huggingface/hub-docs/blob/main/docs/hub/model-cards.md)
- [Common pitfalls in sharing models on HF](https://huggingface.co/blog/FriendliAI/common-pitfalls-in-sharing-models-on-hugging-face)