csh
/
playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
playbook/antigravity-awesome-skills/skills/hugging-face-paper-publisher/examples/example_usage.md

8.3 KiB
Raw Permalink Blame History

Example Usage: HF Paper Publisher Skill

This document demonstrates common workflows for publishing research papers on Hugging Face Hub.

Example 1: Index an Existing arXiv Paper

If you've already published a paper on arXiv and want to make it discoverable on Hugging Face:

# Check if paper exists
uv run scripts/paper_manager.py check --arxiv-id "2301.12345"

# Index the paper
uv run scripts/paper_manager.py index --arxiv-id "2301.12345"

# Get paper information
uv run scripts/paper_manager.py info --arxiv-id "2301.12345"

Expected output:

{
  "exists": true,
  "url": "https://huggingface.co/papers/2301.12345",
  "arxiv_id": "2301.12345",
  "arxiv_url": "https://arxiv.org/abs/2301.12345"
}

Example 2: Link Paper to Your Model

After indexing a paper, link it to your model repository:

# Link single paper
uv run scripts/paper_manager.py link \
  --repo-id "username/my-awesome-model" \
  --repo-type "model" \
  --arxiv-id "2301.12345"

# Link multiple papers
uv run scripts/paper_manager.py link \
  --repo-id "username/my-awesome-model" \
  --repo-type "model" \
  --arxiv-ids "2301.12345,2302.67890"

This will:

  1. Download the model's README.md
  2. Add or update YAML frontmatter
  3. Insert paper references with links
  4. Upload the updated README
  5. Hub automatically creates arxiv:2301.12345 tags

Example 3: Link Paper to Dataset

Same process for datasets:

uv run scripts/paper_manager.py link \
  --repo-id "username/my-dataset" \
  --repo-type "dataset" \
  --arxiv-id "2301.12345" \
  --citation "$(cat citation.bib)"

Example 4: Create a New Research Article

Generate a research paper from template:

# Create with standard template
uv run scripts/paper_manager.py create \
  --template "standard" \
  --title "Efficient Fine-Tuning of Large Language Models" \
  --authors "Jane Doe, John Smith" \
  --abstract "We propose a novel approach to fine-tuning..." \
  --output "paper.md"

# Create with modern template
uv run scripts/paper_manager.py create \
  --template "modern" \
  --title "Vision Transformers for Medical Imaging" \
  --output "medical_vit_paper.md"

# Create ML experiment report
uv run scripts/paper_manager.py create \
  --template "ml-report" \
  --title "BERT Fine-tuning Experiment Results" \
  --output "bert_experiment_report.md"

Example 5: Generate Citations

Get formatted citations for papers:

# BibTeX format
uv run scripts/paper_manager.py citation \
  --arxiv-id "2301.12345" \
  --format "bibtex"

Output:

@article{arxiv2301_12345,
  title={Efficient Fine-Tuning of Large Language Models},
  author={Doe, Jane and Smith, John},
  journal={arXiv preprint arXiv:2301.12345},
  year={2023}
}

Example 6: Complete Workflow - New Paper

Full workflow from paper creation to publication:

# Step 1: Create research article
uv run scripts/paper_manager.py create \
  --template "modern" \
  --title "Novel Architecture for Multimodal Learning" \
  --authors "Alice Chen, Bob Kumar" \
  --output "multimodal_paper.md"

# Step 2: Edit the paper (use your favorite editor)
# vim multimodal_paper.md

# Step 3: Submit to arXiv (external process)
# Upload to arxiv.org, receive arXiv ID: 2312.99999

# Step 4: Index on Hugging Face
uv run scripts/paper_manager.py index --arxiv-id "2312.99999"

# Step 5: Link to your models/datasets
uv run scripts/paper_manager.py link \
  --repo-id "alice/multimodal-model-v1" \
  --repo-type "model" \
  --arxiv-id "2312.99999"

uv run scripts/paper_manager.py link \
  --repo-id "alice/multimodal-dataset" \
  --repo-type "dataset" \
  --arxiv-id "2312.99999"

# Step 6: Generate citation for README
uv run scripts/paper_manager.py citation \
  --arxiv-id "2312.99999" \
  --format "bibtex" > citation.bib

Example 7: Batch Link Papers

Link multiple papers to multiple repositories:

#!/bin/bash

# List of papers
PAPERS=("2301.12345" "2302.67890" "2303.11111")

# List of models
MODELS=("username/model-a" "username/model-b" "username/model-c")

# Link each paper to each model
for paper in "${PAPERS[@]}"; do
  for model in "${MODELS[@]}"; do
    echo "Linking $paper to $model..."
    uv run scripts/paper_manager.py link \
      --repo-id "$model" \
      --repo-type "model" \
      --arxiv-id "$paper"
  done
done

Example 8: Update Model Card with Paper Info

Get paper info and manually update model card:

# Get paper information
uv run scripts/paper_manager.py info \
  --arxiv-id "2301.12345" \
  --format "text" > paper_info.txt

# View the information
cat paper_info.txt

# Manually incorporate into your model card or use the link command

Example 9: Search and Discover Papers

# Search for papers (opens browser)
uv run scripts/paper_manager.py search \
  --query "transformer attention mechanism"

Example 10: Working with tfrere's Template

This skill complements tfrere's research article template:

# 1. Use tfrere's Space to create a beautiful web-based paper
# Visit: https://huggingface.co/spaces/tfrere/research-article-template

# 2. Export your paper content to markdown

# 3. Submit to arXiv

# 4. Use this skill to index and link
uv run scripts/paper_manager.py index --arxiv-id "YOUR_ARXIV_ID"
uv run scripts/paper_manager.py link \
  --repo-id "your-username/your-model" \
  --arxiv-id "YOUR_ARXIV_ID"

Example 11: Error Handling

# Check if paper exists before linking
if uv run scripts/paper_manager.py check --arxiv-id "2301.12345" | grep -q '"exists": true'; then
  echo "Paper exists, proceeding with link..."
  uv run scripts/paper_manager.py link \
    --repo-id "username/model" \
    --arxiv-id "2301.12345"
else
  echo "Paper doesn't exist, indexing first..."
  uv run scripts/paper_manager.py index --arxiv-id "2301.12345"
  uv run scripts/paper_manager.py link \
    --repo-id "username/model" \
    --arxiv-id "2301.12345"
fi

Example 12: CI/CD Integration

Add to your .github/workflows/update-paper.yml:

name: Update Paper Links

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up uv
        uses: astral-sh/setup-uv@v5

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Link paper to model
        env:
          HF_TOKEN: ${{ secrets.HF_TOKEN }}
        run: |
          uv run scripts/paper_manager.py link \
            --repo-id "${{ github.repository_owner }}/model-name" \
            --repo-type "model" \
            --arxiv-id "2301.12345"

Tips and Best Practices

  1. Always check if paper exists before indexing to avoid unnecessary operations
  2. Use meaningful commit messages when linking papers to repositories
  3. Include full citations in model cards for proper attribution
  4. Link papers to all relevant artifacts (models, datasets, spaces)
  5. Generate BibTeX citations for easy reference by others
  6. Keep paper visibility updated in your HF profile settings
  7. Use templates consistently within your research group
  8. Version control your papers alongside code

Troubleshooting

Paper not found after indexing

# Visit the URL directly to trigger indexing
open "https://huggingface.co/papers/2301.12345"

# Wait a few seconds, then check again
uv run scripts/paper_manager.py check --arxiv-id "2301.12345"

Permission denied when linking

# Verify your token has write access
echo $HF_TOKEN

# Set token if missing
export HF_TOKEN="your_token_here"

# Or use .env file
echo "HF_TOKEN=your_token_here" > .env

arXiv ID format issues

# The script handles various formats:
uv run scripts/paper_manager.py check --arxiv-id "2301.12345"
uv run scripts/paper_manager.py check --arxiv-id "arxiv:2301.12345"
uv run scripts/paper_manager.py check --arxiv-id "https://arxiv.org/abs/2301.12345"

# All are equivalent and will be normalized

Next Steps