@synsci/cli-darwin-x64 1.1.49

package/bin/skills/hugging-face-tool-builder/references/hf_model_papers_auth.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+
+# Hugging Face Model Papers Tool with Authentication
+# Fetches papers referenced by Hugging Face models using HF_TOKEN if available
+
+set -euo pipefail
+
+# Help function
+show_help() {
+    cat << EOF
+Hugging Face Model Papers Tool with Authentication
+
+This tool fetches papers referenced by Hugging Face models.
+Supports authentication via HF_TOKEN environment variable.
+
+Usage:
+    $0 [OPTIONS]
+
+Options:
+    MODEL_ID            Specific model to analyze (e.g., microsoft/DialoGPT-medium)
+    --trending [N]      Show papers for top N trending models (default: 5)
+    --help              Show this help message
+
+Environment Variables:
+    HF_TOKEN            Hugging Face API token (optional, for private models)
+
+Examples:
+    # Get papers for a specific model
+    $0 microsoft/DialoGPT-medium
+
+    # Get papers with authentication
+    HF_TOKEN=your_token_here $0 your-private-model
+
+    # Get papers for top 3 trending models
+    $0 --trending 3
+
+EOF
+}
+
+# Function to make authenticated API calls
+hf_api_call() {
+    local url="$1"
+    local headers=()
+    
+    # Add authentication header if HF_TOKEN is set
+    if [[ -n "${HF_TOKEN:-}" ]]; then
+        headers+=(-H "Authorization: Bearer $HF_TOKEN")
+    fi
+    
+    curl -s "${headers[@]}" "$url" 2>/dev/null || echo '{"error": "Network error"}'
+}
+
+# Function to extract papers from text
+extract_papers() {
+    local text="$1"
+    local title="$2"
+    
+    echo "$title"
+    
+    # Find ArXiv URLs
+    local arxiv_urls=$(echo "$text" | grep -oE 'https?://arxiv\.org/[^[:space:]\])]+' | head -5)
+    if [[ -n "$arxiv_urls" ]]; then
+        echo "ArXiv Papers:"
+        echo "$arxiv_urls" | sed 's/^/  • /'
+    fi
+    
+    # Find DOI URLs
+    local doi_urls=$(echo "$text" | grep -oE 'https?://doi\.org/[^[:space:]\])]+' | head -3)
+    if [[ -n "$doi_urls" ]]; then
+        echo "DOI Papers:"
+        echo "$doi_urls" | sed 's/^/  • /'
+    fi
+    
+    # Find arxiv IDs in format YYYY.NNNNN
+    local arxiv_ids=$(echo "$text" | grep -oE 'arXiv:[0-9]{4}\.[0-9]{4,5}' | head -5)
+    if [[ -n "$arxiv_ids" ]]; then
+        echo "ArXiv IDs:"
+        echo "$arxiv_ids" | sed 's/^/  • /'
+    fi
+    
+    # Check for paper mentions
+    if echo "$text" | grep -qi "paper\|publication\|citation"; then
+        local paper_mentions=$(echo "$text" | grep -i -A1 -B1 "paper\|publication" | head -6)
+        if [[ -n "$paper_mentions" ]]; then
+            echo "Paper mentions:"
+            echo "$paper_mentions" | sed 's/^/  /'
+        fi
+    fi
+    
+    if [[ -z "$arxiv_urls" && -z "$doi_urls" && -z "$arxiv_ids" ]]; then
+        echo "No papers found in model card"
+    fi
+}
+
+# Function to get model papers
+get_model_papers() {
+    local model_id="$1"
+    
+    echo "=== $model_id ==="
+    
+    # Get model info from API with authentication
+    local api_url="https://huggingface.co/api/models/$model_id"
+    local response=$(hf_api_call "$api_url")
+    
+    if echo "$response" | grep -q '"error"'; then
+        echo "Error: Could not fetch model '$model_id'"
+        if [[ -z "${HF_TOKEN:-}" ]]; then
+            echo "Note: This might be a private model. Try setting HF_TOKEN environment variable."
+        fi
+        return 1
+    fi
+    
+    # Parse basic info
+    local downloads=$(echo "$response" | jq -r '.downloads // 0')
+    local likes=$(echo "$response" | jq -r '.likes // 0')
+    echo "Downloads: $downloads | Likes: $likes"
+    
+    # Get model card
+    local card_url="https://huggingface.co/$model_id/raw/main/README.md"
+    local card_content=$(curl -s "$card_url" 2>/dev/null || echo "")
+    
+    if [[ -n "$card_content" ]]; then
+        extract_papers "$card_content" "Papers from model card:"
+    else
+        echo "Could not fetch model card"
+    fi
+    
+    # Check tags for arxiv references
+    local arxiv_tag=$(echo "$response" | jq -r '.tags[]' 2>/dev/null | grep arxiv || true)
+    if [[ -n "$arxiv_tag" ]]; then
+        echo "ArXiv from tags: $arxiv_tag"
+    fi
+    
+    echo
+}
+
+# Function to get trending models
+get_trending_models() {
+    local limit="${1:-5}"
+    
+    echo "Fetching top $limit trending models..."
+    
+    local trending_url="https://huggingface.co/api/trending?type=model&limit=$limit"
+    local response=$(hf_api_call "$trending_url")
+    
+    echo "$response" | jq -r '.recentlyTrending[] | .repoData.id' | head -"$limit" | while read -r model_id; do
+        if [[ -n "$model_id" ]]; then
+            get_model_papers "$model_id"
+        fi
+    done
+}
+
+# Main
+if [[ $# -eq 0 ]]; then
+    echo "Error: No arguments provided"
+    show_help
+    exit 1
+fi
+
+if [[ "$1" == "--help" ]]; then
+    show_help
+    exit 0
+elif [[ "$1" == "--trending" ]]; then
+    if [[ -n "${2:-}" ]] && [[ "$2" =~ ^[0-9]+$ ]]; then
+        get_trending_models "$2"
+    else
+        get_trending_models 5
+    fi
+else
+    get_model_papers "$1"
+fi

package/bin/skills/hugging-face-trackio/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: hugging-face-trackio
+description: Track and visualize ML training experiments with Trackio. Use when logging metrics during training (Python API) or retrieving/analyzing logged metrics (CLI). Supports real-time dashboard visualization, HF Space syncing, and JSON output for automation.
+version: 1.0.0
+author: Synthetic Sciences
+license: MIT
+tags: [Hugging Face, Experiment Tracking, Logging, Metrics]
+dependencies: [huggingface-hub, transformers]
+---
+
+# Trackio - Experiment Tracking for ML Training
+
+Trackio is an experiment tracking library for logging and visualizing ML training metrics. It syncs to Hugging Face Spaces for real-time monitoring dashboards.
+
+## Two Interfaces
+
+| Task | Interface | Reference |
+|------|-----------|-----------|
+| **Logging metrics** during training | Python API | [references/logging_metrics.md](references/logging_metrics.md) |
+| **Retrieving metrics** after/during training | CLI | [references/retrieving_metrics.md](references/retrieving_metrics.md) |
+
+## When to Use Each
+
+### Python API → Logging
+
+Use `import trackio` in your training scripts to log metrics:
+
+- Initialize tracking with `trackio.init()`
+- Log metrics with `trackio.log()` or use TRL's `report_to="trackio"`
+- Finalize with `trackio.finish()`
+
+**Key concept**: For remote/cloud training, pass `space_id` — metrics sync to a Space dashboard so they persist after the instance terminates.
+
+→ See [references/logging_metrics.md](references/logging_metrics.md) for setup, TRL integration, and configuration options.
+
+### CLI → Retrieving
+
+Use the `trackio` command to query logged metrics:
+
+- `trackio list projects/runs/metrics` — discover what's available
+- `trackio get project/run/metric` — retrieve summaries and values
+- `trackio show` — launch the dashboard
+- `trackio sync` — sync to HF Space
+
+**Key concept**: Add `--json` for programmatic output suitable for automation and LLM agents.
+
+→ See [references/retrieving_metrics.md](references/retrieving_metrics.md) for all commands, workflows, and JSON output formats.
+
+## Minimal Logging Setup
+
+```python
+import trackio
+
+trackio.init(project="my-project", space_id="username/trackio")
+trackio.log({"loss": 0.1, "accuracy": 0.9})
+trackio.log({"loss": 0.09, "accuracy": 0.91})
+trackio.finish()
+```
+
+### Minimal Retrieval
+
+```bash
+trackio list projects --json
+trackio get metric --project my-project --run my-run --metric loss --json
+```

package/bin/skills/hugging-face-trackio/references/logging_metrics.md

@@ -0,0 +1,206 @@
+# Logging Metrics with Trackio
+
+**Trackio** is a lightweight, free experiment tracking library from Hugging Face. It provides a wandb-compatible API for logging metrics with local-first design.
+
+- **GitHub**: [gradio-app/trackio](https://github.com/gradio-app/trackio)
+- **Docs**: [huggingface.co/docs/trackio](https://huggingface.co/docs/trackio/index)
+
+## Installation
+
+```bash
+pip install trackio
+# or
+uv pip install trackio
+```
+
+## Core API
+
+### Basic Usage
+
+```python
+import trackio
+
+# Initialize a run
+trackio.init(
+    project="my-project",
+    config={"learning_rate": 0.001, "epochs": 10}
+)
+
+# Log metrics during training
+for epoch in range(10):
+    loss = train_epoch()
+    trackio.log({"loss": loss, "epoch": epoch})
+
+# Finalize the run
+trackio.finish()
+```
+
+### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `trackio.init(...)` | Start a new tracking run |
+| `trackio.log(dict)` | Log metrics (called repeatedly during training) |
+| `trackio.finish()` | Finalize run and ensure all metrics are saved |
+| `trackio.show()` | Launch the local dashboard |
+| `trackio.sync(...)` | Sync local project to HF Space |
+
+## trackio.init() Parameters
+
+```python
+trackio.init(
+    project="my-project",           # Project name (groups runs together)
+    name="run-name",                # Optional: name for this specific run
+    config={...},                   # Hyperparameters and config to log
+    space_id="username/trackio",    # Optional: sync to HF Space for remote dashboard
+    group="experiment-group",       # Optional: group related runs
+)
+```
+
+## Local vs Remote Dashboard
+
+### Local (Default)
+
+By default, trackio stores metrics in a local SQLite database and runs the dashboard locally:
+
+```python
+trackio.init(project="my-project")
+# ... training ...
+trackio.finish()
+
+# Launch local dashboard
+trackio.show()
+```
+
+Or from terminal:
+```bash
+trackio show --project my-project
+```
+
+### Remote (HF Space)
+
+Pass `space_id` to sync metrics to a Hugging Face Space for persistent, shareable dashboards:
+
+```python
+trackio.init(
+    project="my-project",
+    space_id="username/trackio"  # Auto-creates Space if it doesn't exist
+)
+```
+
+⚠️ **For remote training** (cloud GPUs, HF Jobs, etc.): Always use `space_id` since local storage is lost when the instance terminates.
+
+### Sync Local to Remote
+
+Sync existing local projects to a Space:
+
+```python
+trackio.sync(project="my-project", space_id="username/my-experiments")
+```
+
+## wandb Compatibility
+
+Trackio is API-compatible with wandb. Drop-in replacement:
+
+```python
+import trackio as wandb
+
+wandb.init(project="my-project")
+wandb.log({"loss": 0.5})
+wandb.finish()
+```
+
+## TRL Integration
+
+When using TRL trainers, set `report_to="trackio"` for automatic metric logging:
+
+```python
+from trl import SFTConfig, SFTTrainer
+import trackio
+
+trackio.init(
+    project="sft-training",
+    space_id="username/trackio",
+    config={"model": "Qwen/Qwen2.5-0.5B", "dataset": "trl-lib/Capybara"}
+)
+
+config = SFTConfig(
+    output_dir="./output",
+    report_to="trackio",  # Automatic metric logging
+    # ... other config
+)
+
+trainer = SFTTrainer(model=model, args=config, ...)
+trainer.train()
+trackio.finish()
+```
+
+## What Gets Logged
+
+With TRL/Transformers integration, trackio automatically captures:
+- Training loss
+- Learning rate
+- Eval metrics
+- Training throughput
+
+For manual logging, log any numeric metrics:
+
+```python
+trackio.log({
+    "train_loss": 0.5,
+    "train_accuracy": 0.85,
+    "val_loss": 0.4,
+    "val_accuracy": 0.88,
+    "epoch": 1
+})
+```
+
+## Grouping Runs
+
+Use `group` to organize related experiments in the dashboard sidebar:
+
+```python
+# Group by experiment type
+trackio.init(project="my-project", name="baseline-v1", group="baseline")
+trackio.init(project="my-project", name="augmented-v1", group="augmented")
+
+# Group by hyperparameter
+trackio.init(project="hyperparam-sweep", name="lr-0.001", group="lr_0.001")
+trackio.init(project="hyperparam-sweep", name="lr-0.01", group="lr_0.01")
+```
+
+## Configuration Best Practices
+
+Keep config minimal — only log what's useful for comparing runs:
+
+```python
+trackio.init(
+    project="qwen-sft-capybara",
+    name="baseline-lr2e5",
+    config={
+        "model": "Qwen/Qwen2.5-0.5B",
+        "dataset": "trl-lib/Capybara",
+        "learning_rate": 2e-5,
+        "num_epochs": 3,
+        "batch_size": 8,
+    }
+)
+```
+
+## Embedding Dashboards
+
+Embed Space dashboards in websites with query parameters:
+
+```html
+<iframe 
+  src="https://username-trackio.hf.space/?project=my-project&metrics=train_loss,val_loss&sidebar=hidden" 
+  style="width:1600px; height:500px; border:0;">
+</iframe>
+```
+
+Query parameters:
+- `project`: Filter to specific project
+- `metrics`: Comma-separated metric names to show
+- `sidebar`: `hidden` or `collapsed`
+- `smoothing`: 0-20 (smoothing slider value)
+- `xmin`, `xmax`: X-axis limits

package/bin/skills/hugging-face-trackio/references/retrieving_metrics.md

@@ -0,0 +1,223 @@
+# Retrieving Metrics with Trackio CLI
+
+The `trackio` CLI provides direct terminal access to query Trackio experiment tracking data locally without needing to start the MCP server.
+
+## Quick Command Reference
+
+| Task | Command |
+|------|---------|
+| List projects | `trackio list projects` |
+| List runs | `trackio list runs --project <name>` |
+| List metrics | `trackio list metrics --project <name> --run <name>` |
+| List system metrics | `trackio list system-metrics --project <name> --run <name>` |
+| Get project summary | `trackio get project --project <name>` |
+| Get run summary | `trackio get run --project <name> --run <name>` |
+| Get metric values | `trackio get metric --project <name> --run <name> --metric <name>` |
+| Get system metrics | `trackio get system-metric --project <name> --run <name>` |
+| Show dashboard | `trackio show [--project <name>]` |
+| Sync to Space | `trackio sync --project <name> --space-id <space_id>` |
+
+## Core Commands
+
+### List Commands
+
+```bash
+trackio list projects                                    # List all projects
+trackio list projects --json                            # JSON output
+
+trackio list runs --project <name>                      # List runs in project
+trackio list runs --project <name> --json               # JSON output
+
+trackio list metrics --project <name> --run <name>      # List metrics for run
+trackio list metrics --project <name> --run <name> --json
+
+trackio list system-metrics --project <name> --run <name>  # List system metrics
+trackio list system-metrics --project <name> --run <name> --json
+```
+
+### Get Commands
+
+```bash
+trackio get project --project <name>                    # Project summary
+trackio get project --project <name> --json             # JSON output
+
+trackio get run --project <name> --run <name>           # Run summary
+trackio get run --project <name> --run <name> --json
+
+trackio get metric --project <name> --run <name> --metric <name>  # Metric values
+trackio get metric --project <name> --run <name> --metric <name> --json
+
+trackio get system-metric --project <name> --run <name>           # All system metrics
+trackio get system-metric --project <name> --run <name> --metric <name>  # Specific metric
+trackio get system-metric --project <name> --run <name> --json
+```
+
+### Dashboard Commands
+
+```bash
+trackio show                                              # Launch dashboard
+trackio show --project <name>                           # Load specific project
+trackio show --theme <theme>                            # Custom theme
+trackio show --mcp-server                                # Enable MCP server
+trackio show --color-palette "#FF0000,#00FF00"         # Custom colors
+```
+
+### Sync Commands
+
+```bash
+trackio sync --project <name> --space-id <space_id>     # Sync to HF Space
+trackio sync --project <name> --space-id <space_id> --private  # Private space
+trackio sync --project <name> --space-id <space_id> --force   # Overwrite
+```
+
+## Output Formats
+
+All `list` and `get` commands support two output formats:
+
+- **Human-readable** (default): Formatted text for terminal viewing
+- **JSON** (with `--json` flag): Structured JSON for programmatic use
+
+## Common Patterns
+
+### Discover Projects and Runs
+
+```bash
+# List all available projects
+trackio list projects
+
+# List runs in a project
+trackio list runs --project my-project
+
+# Get project overview
+trackio get project --project my-project --json
+```
+
+### Inspect Run Details
+
+```bash
+# Get run summary with all metrics
+trackio get run --project my-project --run my-run --json
+
+# List available metrics
+trackio list metrics --project my-project --run my-run
+
+# Get specific metric values
+trackio get metric --project my-project --run my-run --metric loss --json
+```
+
+### Query System Metrics
+
+```bash
+# List system metrics (GPU, etc.)
+trackio list system-metrics --project my-project --run my-run
+
+# Get all system metric data
+trackio get system-metric --project my-project --run my-run --json
+
+# Get specific system metric
+trackio get system-metric --project my-project --run my-run --metric gpu_utilization --json
+```
+
+### Automation Scripts
+
+```bash
+# Extract latest metric value
+LATEST_LOSS=$(trackio get metric --project my-project --run my-run --metric loss --json | jq -r '.values[-1].value')
+
+# Export run summary to file
+trackio get run --project my-project --run my-run --json > run_summary.json
+
+# Filter runs with jq
+trackio list runs --project my-project --json | jq '.runs[] | select(startswith("train"))'
+```
+
+### LLM Agent Workflow
+
+```bash
+# 1. Discover available projects
+trackio list projects --json
+
+# 2. Explore project structure
+trackio get project --project my-project --json
+
+# 3. Inspect specific run
+trackio get run --project my-project --run my-run --json
+
+# 4. Query metric values
+trackio get metric --project my-project --run my-run --metric accuracy --json
+```
+
+## Error Handling
+
+Commands validate inputs and return clear errors:
+
+- Missing project: `Error: Project '<name>' not found.`
+- Missing run: `Error: Run '<name>' not found in project '<project>'.`
+- Missing metric: `Error: Metric '<name>' not found in run '<run>' of project '<project>'.`
+
+All errors exit with non-zero status code and write to stderr.
+
+## Key Options
+
+- `--project`: Project name (required for most commands)
+- `--run`: Run name (required for run-specific commands)
+- `--metric`: Metric name (required for metric-specific commands)
+- `--json`: Output in JSON format instead of human-readable
+- `--theme`: Dashboard theme (for `show` command)
+- `--mcp-server`: Enable MCP server mode (for `show` command)
+- `--color-palette`: Comma-separated hex colors (for `show` command)
+- `--private`: Create private Space (for `sync` command)
+- `--force`: Overwrite existing database (for `sync` command)
+
+## JSON Output Structure
+
+### List Projects
+```json
+{"projects": ["project1", "project2"]}
+```
+
+### List Runs
+```json
+{"project": "my-project", "runs": ["run1", "run2"]}
+```
+
+### Project Summary
+```json
+{
+  "project": "my-project",
+  "num_runs": 3,
+  "runs": ["run1", "run2", "run3"],
+  "last_activity": 100
+}
+```
+
+### Run Summary
+```json
+{
+  "project": "my-project",
+  "run": "my-run",
+  "num_logs": 50,
+  "metrics": ["loss", "accuracy"],
+  "config": {"learning_rate": 0.001},
+  "last_step": 49
+}
+```
+
+### Metric Values
+```json
+{
+  "project": "my-project",
+  "run": "my-run",
+  "metric": "loss",
+  "values": [
+    {"step": 0, "timestamp": "2024-01-01T00:00:00", "value": 0.5},
+    {"step": 1, "timestamp": "2024-01-01T00:01:00", "value": 0.4}
+  ]
+}
+```
+
+## References
+
+- **Complete CLI documentation**: See [docs/source/cli_commands.md](docs/source/cli_commands.md)
+- **API and MCP Server**: See [docs/source/api_mcp_server.md](docs/source/api_mcp_server.md)
+