tribunal-kit 9.2.1 → 9.2.4

package/.agent/skills/huggingface-paper-publisher/examples/example_usage.md

@@ -0,0 +1,326 @@
+# 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:
+
+```bash
+# 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:
+```json
+{
+  "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:
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+# BibTeX format
+uv run scripts/paper_manager.py citation \
+  --arxiv-id "2301.12345" \
+  --format "bibtex"
+```
+
+Output:
+```bibtex
+@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:
+
+```bash
+# 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:
+
+```bash
+#!/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:
+
+```bash
+# 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
+
+```bash
+# 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](https://huggingface.co/spaces/tfrere/research-article-template):
+
+```bash
+# 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
+
+```bash
+# 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`:
+
+```yaml
+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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+- Explore the [Paper Pages documentation](https://huggingface.co/docs/hub/en/paper-pages)
+- Check out [tfrere's research template](https://huggingface.co/spaces/tfrere/research-article-template)
+- Browse [papers on HF](https://huggingface.co/papers)
+- Learn about [model cards](https://huggingface.co/docs/hub/en/model-cards)

package/.agent/skills/huggingface-paper-publisher/references/quick_reference.md

@@ -0,0 +1,216 @@
+# Quick Reference Guide
+
+## Essential Commands
+
+### Paper Indexing
+```bash
+# Index from arXiv
+uv run scripts/paper_manager.py index --arxiv-id "2301.12345"
+
+# Check if exists
+uv run scripts/paper_manager.py check --arxiv-id "2301.12345"
+```
+
+### Linking Papers
+```bash
+# Link to model
+uv run scripts/paper_manager.py link \
+  --repo-id "username/model" \
+  --repo-type "model" \
+  --arxiv-id "2301.12345"
+
+# Link to dataset
+uv run scripts/paper_manager.py link \
+  --repo-id "username/dataset" \
+  --repo-type "dataset" \
+  --arxiv-id "2301.12345"
+
+# Link multiple papers
+uv run scripts/paper_manager.py link \
+  --repo-id "username/model" \
+  --repo-type "model" \
+  --arxiv-ids "2301.12345,2302.67890"
+```
+
+### Creating Papers
+```bash
+# Standard template
+uv run scripts/paper_manager.py create \
+  --template "standard" \
+  --title "Paper Title" \
+  --output "paper.md"
+
+# Modern template
+uv run scripts/paper_manager.py create \
+  --template "modern" \
+  --title "Paper Title" \
+  --authors "Author1, Author2" \
+  --abstract "Abstract text" \
+  --output "paper.md"
+
+# ML Report
+uv run scripts/paper_manager.py create \
+  --template "ml-report" \
+  --title "Experiment Report" \
+  --output "report.md"
+
+# arXiv style
+uv run scripts/paper_manager.py create \
+  --template "arxiv" \
+  --title "Paper Title" \
+  --output "paper.md"
+```
+
+### Citations
+```bash
+# Generate BibTeX
+uv run scripts/paper_manager.py citation \
+  --arxiv-id "2301.12345" \
+  --format "bibtex"
+```
+
+### Paper Info
+```bash
+# JSON format
+uv run scripts/paper_manager.py info \
+  --arxiv-id "2301.12345" \
+  --format "json"
+
+# Text format
+uv run scripts/paper_manager.py info \
+  --arxiv-id "2301.12345" \
+  --format "text"
+```
+
+## URL Formats
+
+### Hugging Face Paper Pages
+- View paper: `https://huggingface.co/papers/{arxiv-id}`
+- Example: `https://huggingface.co/papers/2301.12345`
+
+### arXiv
+- Abstract: `https://arxiv.org/abs/{arxiv-id}`
+- PDF: `https://arxiv.org/pdf/{arxiv-id}.pdf`
+- Example: `https://arxiv.org/abs/2301.12345`
+
+## YAML Metadata Format
+
+### Model Card
+```yaml
+---
+language:
+  - en
+license: apache-2.0
+tags:
+  - text-generation
+  - transformers
+library_name: transformers
+---
+```
+
+### Dataset Card
+```yaml
+---
+language:
+  - en
+license: cc-by-4.0
+task_categories:
+  - text-generation
+size_categories:
+  - 10K<n<100K
+---
+```
+
+## arXiv ID Formats
+
+All these formats work:
+- `2301.12345`
+- `arxiv:2301.12345`
+- `https://arxiv.org/abs/2301.12345`
+- `https://arxiv.org/pdf/2301.12345.pdf`
+
+## Environment Setup
+
+### Set Token
+```bash
+export HF_TOKEN="your_token"
+```
+
+### Or use .env file
+```bash
+echo "HF_TOKEN=your_token" > .env
+```
+
+## Common Workflows
+
+### 1. Index & Link
+```bash
+uv run scripts/paper_manager.py index --arxiv-id "2301.12345"
+uv run scripts/paper_manager.py link --repo-id "user/model" --arxiv-id "2301.12345"
+```
+
+### 2. Create & Publish
+```bash
+uv run scripts/paper_manager.py create --template "modern" --title "Title" --output "paper.md"
+# Edit paper.md
+# Submit to arXiv → get ID
+uv run scripts/paper_manager.py index --arxiv-id "NEW_ID"
+uv run scripts/paper_manager.py link --repo-id "user/model" --arxiv-id "NEW_ID"
+```
+
+### 3. Batch Link
+```bash
+for id in "2301.12345" "2302.67890"; do
+  uv run scripts/paper_manager.py link --repo-id "user/model" --arxiv-id "$id"
+done
+```
+
+## Troubleshooting
+
+### Paper not found
+Visit `https://huggingface.co/papers/{arxiv-id}` to trigger indexing
+
+### Permission denied
+Check `HF_TOKEN` is set and has write access
+
+### arXiv API errors
+Wait a moment and retry - arXiv has rate limits
+
+## Tips
+
+1. Always check paper exists before linking
+2. Use templates for consistency
+3. Include full citations in model cards
+4. Link papers to all relevant artifacts
+5. Keep citations up to date
+
+## Templates Available
+
+- `standard` - Traditional academic paper
+- `modern` - Web-friendly format (Distill-style)
+- `arxiv` - arXiv journal format
+- `ml-report` - ML experiment documentation
+
+## File Locations
+
+- Scripts: `scripts/paper_manager.py`
+- Templates: `templates/*.md`
+- Examples: `examples/example_usage.md`
+- This guide: `references/quick_reference.md`
+
+## Getting Help
+
+```bash
+# Command help
+uv run scripts/paper_manager.py --help
+
+# Subcommand help
+uv run scripts/paper_manager.py link --help
+```
+
+## Additional Resources
+
+- [Full documentation](../SKILL.md)
+- [Usage examples](../examples/example_usage.md)
+- [HF Paper Pages](https://huggingface.co/papers)
+- [tfrere's template](https://huggingface.co/spaces/tfrere/research-article-template)