@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/scientific-figure-making/references/tutorials.md

@@ -0,0 +1,135 @@
+# Tutorials: End-to-End Publication Figures
+
+Implement the API described in [api.md](api.md) in your own code (constants, style, plot helpers, finalize). This repository does not currently ship a tracked shared Python module that defines `apply_publication_style`, `make_grouped_bar`, or the other helpers directly; their signatures and behavior are specified in [api.md](api.md) and should be implemented or adapted per project. For real-world scripts that follow this style, see [demos.md](demos.md) (links to the [figures4papers](https://github.com/ChenLiu-1996/figures4papers) `figure_*` folders).
+
+If venue, approximate dimensions, or export formats are missing and they would change layout or DPI, ask before locking choices. For unattended scripts, set a non-interactive matplotlib backend (for example `matplotlib.use("Agg")`) before importing `pyplot`. Finish with `finalize_figure` as in [api.md](api.md).
+
+---
+
+## Tutorial 1: Grouped bar chart
+
+**Goal:** One grouped bar chart: several series compared on the same categorical x-axis (metrics, conditions, tasks, or similar), optional value annotations, and export via `finalize_figure`.
+
+**Checklist:**
+
+- [ ] Load or define data: shared category list for the x-axis; one numeric array per series (each aligned with those categories); legend label per series.
+- [ ] Call `apply_publication_style` with a style (e.g. `FigureStyle(font_size=24, axes_linewidth=3)` for a large panel).
+- [ ] Create figure and one axis; widen `figsize` when there are many categories so ticks and labels stay readable.
+- [ ] Call `make_grouped_bar(ax, categories, series, labels, ylabel="...", annotate=True)` (or `annotate=False` and use `annotate_bars` separately per [api.md](api.md)).
+- [ ] Set y-limits to a range that fits the data (tighten when values sit in a narrow band).
+- [ ] Call `finalize_figure(fig, "output/comparison", formats=["png", "pdf"], dpi=300)`.
+
+**Example flow** (illustrative counts; implement helpers per [api.md](api.md)):
+
+```python
+import matplotlib.pyplot as plt
+
+# Assume you have implemented: apply_publication_style, FigureStyle, make_grouped_bar, finalize_figure, PALETTE (see api.md)
+apply_publication_style(FigureStyle(font_size=24, axes_linewidth=3))
+fig, ax = plt.subplots(figsize=(16, 5))
+
+categories = ["Metric A", "Metric B", "Metric C", "Metric D"]  # length K
+series = [  # one list per series, each length K
+    [0.92, 0.88, 0.85, 0.90],
+    [0.85, 0.82, 0.88, 0.84],
+    [0.78, 0.80, 0.82, 0.79],
+]
+labels = ["Ours", "Baseline X", "Baseline Y"]  # same length as series
+make_grouped_bar(
+    ax, categories, series, labels,
+    ylabel="Score", colors=[PALETTE["blue_main"], PALETTE["green_3"], PALETTE["red_strong"]],
+    annotate=True,
+)
+ax.set_ylim(0.7, 1.0)
+finalize_figure(fig, "output/method_comparison", formats=["png", "pdf"], dpi=300)
+```
+
+---
+
+## Tutorial 2: Multi-panel trend with shared legend
+
+**Goal:** Two trend panels (e.g. train and validation curves) and a third panel used only for the legend.
+
+**Checklist:**
+
+- [ ] Apply style; create 1×3 subplots (or 2×2 with last axis for legend).
+- [ ] Plot trends on the first axes; collect legend handles/labels from one of them.
+- [ ] On the last axis, call `ax.set_axis_off()` and add a legend using the collected handles/labels.
+- [ ] Set y-limits and titles on data panels.
+- [ ] Call `finalize_figure`.
+
+**Example flow** (implement helpers per [api.md](api.md)):
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+
+apply_publication_style(FigureStyle(font_size=14, axes_linewidth=2))
+fig, axes = create_subplots(1, 3, figsize=(14, 4))
+
+x = np.linspace(0, 10, 50)
+y1 = 0.5 + 0.4 * (1 - np.exp(-x / 3))
+y2 = 0.45 + 0.35 * (1 - np.exp(-x / 4))
+make_trend(axes[0], x, [y1, y2], ["Model A", "Model B"], ylabel="Loss", xlabel="Step")
+axes[0].set_title("Training")
+make_trend(axes[1], x, [y1 * 1.1, y2 * 1.05], ["Model A", "Model B"], ylabel="Loss", xlabel="Step")
+axes[1].set_title("Validation")
+
+# Legend-only panel
+handles, labels = axes[0].get_legend_handles_labels()
+axes[2].set_axis_off()
+axes[2].legend(handles, labels, loc="center")
+
+finalize_figure(fig, "output/trends", formats=["png", "pdf"], dpi=300)
+```
+
+---
+
+## Tutorial 3: Heatmap with labels and colorbar
+
+**Goal:** A correlation or score matrix with row/column labels and a colorbar.
+
+**Checklist:**
+
+- [ ] Apply style; create one axis.
+- [ ] Prepare 2D matrix and optional x_labels, y_labels.
+- [ ] Call `make_heatmap(ax, matrix, x_labels=..., y_labels=..., cmap="magma", cbar_label="...")`.
+- [ ] Call `finalize_figure`.
+
+**Example flow** (implement helpers per [api.md](api.md)):
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+
+apply_publication_style(FigureStyle(font_size=12, axes_linewidth=2))
+fig, ax = plt.subplots(figsize=(8, 6))
+np.random.seed(42)
+matrix = np.random.rand(5, 5)
+matrix = (matrix + matrix.T) / 2  # symmetric
+labels = [f"F{i+1}" for i in range(5)]
+make_heatmap(ax, matrix, x_labels=labels, y_labels=labels, cmap="magma", cbar_label="Correlation")
+finalize_figure(fig, "output/heatmap", formats=["png", "pdf"], dpi=300)
+```
+
+---
+
+## Chart types beyond these walkthroughs
+
+These tutorials cover grouped bars, multi-panel trends with a legend column, and heatmaps. For other house-style figures, open the closest match in [demos.md](demos.md), then align constants and `finalize_figure` with [api.md](api.md) and typography or export rules in [design-theory.md](design-theory.md).
+
+- **Radar or polar comparisons:** `figure_VIGIL` (for example `plot_comparison_radar.py`).
+- **Comparison or post-training line panels:** `figure_VIGIL`, `figure_ophthal_review`, or `figure_Cflows`, depending on layout.
+- **Scatter-heavy or schematic panels:** `figure_Dispersion` and `figure_VIGIL` concept plots are good starting points.
+- **Bar-style quantitative comparisons:** `figure_CellSpliceNet`, `figure_ImmunoStruct`, and `figure_brainteaser`.
+- **Heatmap-focused examples:** `figure_RNAGenScape`.
+
+For more layout ideas (ultra-wide panels, legend-only axes, print-safe bars), see [common-patterns.md](common-patterns.md).
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to load this skill
+- [api.md](api.md) — API this tutorial assumes
+- [demos.md](demos.md) — Production scripts in figures4papers
+- [common-patterns.md](common-patterns.md) — Layout and print-safe details
+- [design-theory.md](design-theory.md) — Why the style choices exist

package/dist/skills/semantic-scholar/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: semantic-scholar
+description: Search published venue papers (IEEE, ACM, Springer, etc.) via Semantic Scholar API. Complements /arxiv (preprints) with citation counts, venue metadata, and TLDR. Use when user says "search semantic scholar", "find IEEE papers", "find journal papers", "venue papers", "citation search", or wants published literature beyond arXiv preprints.
+argument-hint: query-or-paper-id
+allowed-tools: Bash(*), Read, Write
+---
+
+# Semantic Scholar Paper Search
+
+Search topic or paper ID: $ARGUMENTS
+
+## Role & Positioning
+
+This skill is the **published venue** counterpart to `/arxiv`:
+
+| Skill | Source | Best for |
+|-------|--------|----------|
+| `/arxiv` | arXiv API | Latest preprints, cutting-edge unrefereed work |
+| `/semantic-scholar` | Semantic Scholar API | **Published** journal/conference papers (IEEE, ACM, Springer, etc.) with citation counts, venue info, TLDR |
+
+**Do NOT duplicate arXiv's job.** If results contain an `externalIds.ArXiv` field, the paper is also on arXiv — note this but do not re-fetch from arXiv.
+
+## Constants
+
+- **MAX_RESULTS = 10** — Default number of search results.
+- **S2_FETCHER** — canonical name `semantic_scholar_fetch.py`, resolved per
+  [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2
+  (Codex-side chain: `$ARIS_REPO/tools/` → `tools/` → `~/.codex/skills/semantic-scholar/`).
+  Policy D1 — if unresolved (canonical chain exhausted), fall back to inline Python.
+- **DEFAULT_FILTERS** — For general research queries, apply these by default to reduce noise:
+  - `--fields-of-study "Computer Science,Engineering"`
+  - `--publication-types JournalArticle,Conference`
+
+> Overrides (append to arguments):
+> - `/semantic-scholar "topic" - max: 20` — return up to 20 results
+> - `/semantic-scholar "topic" - type: journal` — only journal articles
+> - `/semantic-scholar "topic" - type: conference` — only conference papers
+> - `/semantic-scholar "topic" - min-citations: 50` — only highly-cited papers
+> - `/semantic-scholar "topic" - year: 2022-` — papers from 2022 onward
+> - `/semantic-scholar "topic" - fields: all` — remove default field-of-study filter
+> - `/semantic-scholar "topic" - sort: citations` — bulk search sorted by citation count
+> - `/semantic-scholar "DOI:10.1109/..."` — fetch a single paper by DOI
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for directives:
+
+- **Query or ID**: main search term, or a paper identifier:
+  - DOI: `10.1109/TWC.2024.1234567`
+  - Semantic Scholar ID: `f9314fd99be5f2b1b3efcfab87197d578160d553`
+  - ArXiv: `ARXIV:2006.10685`
+  - Corpus: `CorpusId:219792180`
+- **`- max: N`**: override MAX_RESULTS
+- **`- type: journal|conference|review|all`**: map to `--publication-types`
+- **`- min-citations: N`**: map to `--min-citations`
+- **`- year: RANGE`**: map to `--year` (e.g. `2022-`, `2020-2024`)
+- **`- fields: FIELDS`**: override `--fields-of-study` (use `all` to remove filter)
+- **`- sort: citations|date`**: use `search-bulk` with `--sort citationCount:desc` or `publicationDate:desc`
+
+If the argument matches a DOI pattern (`10.XXXX/...`), a Semantic Scholar ID (40-char hex), or a prefixed ID (`ARXIV:...`, `CorpusId:...`), skip search and go directly to Step 3.
+
+### Step 2: Search Papers
+
+Resolve `$S2_FETCHER` via the canonical strict-safe Codex chain
+(see [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2):
+
+```bash
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+S2_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/semantic_scholar_fetch.py" ] && S2_FETCHER="$ARIS_REPO/tools/semantic_scholar_fetch.py"
+[ -z "$S2_FETCHER" ] && [ -f tools/semantic_scholar_fetch.py ] && S2_FETCHER="tools/semantic_scholar_fetch.py"
+[ -z "$S2_FETCHER" ] && [ -f ~/.codex/skills/semantic-scholar/semantic_scholar_fetch.py ] && S2_FETCHER="$HOME/.codex/skills/semantic-scholar/semantic_scholar_fetch.py"
+```
+
+**Standard search** (default — relevance-ranked):
+
+```bash
+[ -n "$S2_FETCHER" ] && python3 "$S2_FETCHER" search "QUERY" --max MAX_RESULTS \
+  --fields-of-study "Computer Science,Engineering" \
+  --publication-types JournalArticle,Conference
+```
+
+**Bulk search** (when `- sort:` is specified, or MAX_RESULTS > 100):
+
+```bash
+[ -n "$S2_FETCHER" ] && python3 "$S2_FETCHER" search-bulk "QUERY" --max MAX_RESULTS \
+  --sort citationCount:desc \
+  --fields-of-study "Computer Science" \
+  --year "2020-"
+```
+
+If `semantic_scholar_fetch.py` is not found, fall back to inline Python using `urllib` against `https://api.semanticscholar.org/graph/v1/paper/search`.
+
+**Recommended filter combos** (from testing):
+
+| Goal | Flags |
+|------|-------|
+| High-quality journal papers | `--publication-types JournalArticle --min-citations 10` |
+| CS/EE papers, recent | `--fields-of-study "Computer Science,Engineering" --year "2022-"` |
+| Foundational / high-impact | `search-bulk --sort citationCount:desc --fields-of-study "Computer Science"` |
+| Conference papers only | `--publication-types Conference` |
+
+> **Note**: `--venue` requires exact venue names (e.g. "IEEE Transactions on Signal Processing"), not partial matches like "IEEE". Avoid using `--venue` in automated flows — prefer `--publication-types` + `--fields-of-study`.
+
+### Step 3: Fetch Details for a Specific Paper
+
+When a single paper ID is requested:
+
+```bash
+[ -n "$S2_FETCHER" ] && python3 "$S2_FETCHER" paper "PAPER_ID"
+```
+
+Where PAPER_ID can be:
+- DOI: `10.1109/TSP.2021.3071210`
+- ArXiv: `ARXIV:2006.10685`
+- CorpusId: `CorpusId:219792180`
+- S2 ID: `f9314fd99be5f2b1b3efcfab87197d578160d553`
+
+### Step 4: De-duplicate Against arXiv
+
+For each result, check `externalIds.ArXiv`:
+- If present → paper is also on arXiv. Note this in output but do NOT re-fetch via `/arxiv`.
+- If absent → paper is **venue-only** (e.g. IEEE without preprint). This is the unique value of this skill.
+
+### Step 5: Present Results
+
+Present results as a table:
+
+```text
+| # | Title | Venue | Year | Citations | Authors | Type |
+|---|-------|-------|------|-----------|---------|------|
+| 1 | Deep Learning Enabled... | IEEE Trans. Signal Process. | 2021 | 1364 | Xie et al. | Journal |
+```
+
+For each paper, also show:
+- **DOI link**: `https://doi.org/DOI` (for IEEE/ACM papers, this is the canonical link)
+- **Open Access PDF**: if `openAccessPdf.url` is non-empty, show it
+- **TLDR**: if available, show the one-line summary
+- **Also on arXiv**: if `externalIds.ArXiv` exists, note the arXiv ID
+
+### Step 6: Detailed Summary
+
+For each paper (or top 5 if many results):
+
+```markdown
+## [Title]
+
+- **Venue**: [venue name] ([publicationVenue.type]: journal/conference)
+- **Year**: [year] | **Citations**: [citationCount]
+- **Authors**: [full author list]
+- **DOI**: [doi link]
+- **Fields**: [fieldsOfStudy]
+- **TLDR**: [tldr.text if available]
+- **Abstract**: [abstract]
+- **Open Access**: [openAccessPdf.url or "Not available"]
+- **Also on arXiv**: [ArXiv ID if exists, else "No"]
+```
+
+### Step 7: Update Research Wiki (if active)
+
+**Required when `research-wiki/` exists in the project**; skip silently
+otherwise. Ingest the papers presented to the user. For results with an
+`externalIds.ArXiv` field, use `--arxiv-id`; for venue-only papers (no
+arXiv mirror — common for IEEE/ACM), fall back to manual metadata:
+
+```
+if [ -d research-wiki/ ]:
+    WIKI_SCRIPT=""
+    [ -n "$ARIS_REPO" ] && [ -f "$ARIS_REPO/tools/research_wiki.py" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"
+    [ -z "$WIKI_SCRIPT" ] && [ -f tools/research_wiki.py ] && WIKI_SCRIPT="tools/research_wiki.py"
+    [ -z "$WIKI_SCRIPT" ] && [ -f ~/.codex/skills/research-wiki/research_wiki.py ] && WIKI_SCRIPT="$HOME/.codex/skills/research-wiki/research_wiki.py"
+    for each paper in results:
+        if paper.externalIds.ArXiv:
+            [ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+                --arxiv-id "<ArXiv>"
+        else:
+            [ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+                --title "<title>" --authors "<authors joined by , >" \
+                --year <year> --venue "<venue>" \
+                [--external-id-doi "<externalIds.DOI>"]
+```
+
+The helper handles slug / dedup / page / index / log — **do not
+handwrite `papers/<slug>.md`**. See
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md).
+Backfill with `/research-wiki sync --arxiv-ids <id1>,<id2>,...` for
+arXiv-available papers.
+
+### Step 8: Final Output
+
+Summarize what was done:
+
+- `Found N published papers for "query"`
+- `Filters applied: [publication types, fields, year range, etc.]`
+- `N papers are venue-only (not on arXiv)`
+- `Wiki-ingested N papers` (if `research-wiki/` was present)
+
+Suggest follow-up skills:
+
+```text
+/arxiv "topic"           - search arXiv preprints (complements this search)
+/research-lit "topic"    - multi-source review: Zotero + local PDFs + arXiv + S2
+/novelty-check "idea"    - verify novelty against literature
+```
+
+## Key Rules
+
+- **Default to filtered search**: Always apply `--fields-of-study` and `--publication-types` unless user says `- fields: all`. Without filters, S2 returns cross-discipline noise (linguistics, psychology, etc.).
+- **Citation count is gold**: S2's citation data is its main advantage over arXiv. Always show `citationCount` prominently and use it to rank/prioritize results.
+- **Venue metadata matters**: Show `venue` and `publicationVenue.type` (journal vs conference) — this helps users assess paper quality.
+- **DOI is the canonical ID for published papers**: Always show DOI links for IEEE/ACM/Springer papers.
+- **Rate limiting**: S2 API without key is heavily rate-limited (~1 req/s, strict cooldown). If HTTP 429 occurs, wait and retry. Recommend users set `SEMANTIC_SCHOLAR_API_KEY` env var for higher limits (free at https://www.semanticscholar.org/product/api#api-key-form).
+- **TLDR may be null**: Some publishers (notably IEEE) elide the TLDR field. Fall back to showing the first sentence of the abstract.
+- **openAccessPdf may be empty**: Many IEEE papers are closed access. Always provide the DOI link as fallback.
+- If the S2 API is unreachable, suggest using `/arxiv` or `/research-lit "topic" - sources: web` as fallback.

package/dist/skills/serverless-modal/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: serverless-modal
+description: "Run GPU workloads on Modal — training, fine-tuning, inference, batch processing. Zero-config serverless: no SSH, no Docker, auto scale-to-zero. Use when user says \"modal run\", \"modal training\", \"modal inference\", \"deploy to modal\", \"need a GPU\", \"run on modal\", \"serverless GPU\", or needs remote GPU compute."
+argument-hint: [task-description]
+allowed-tools: Bash(*), Read, Grep, Glob, Edit, Write
+---
+
+# Modal Cloud GPU — Training & Inference
+
+Task: $ARGUMENTS
+
+## Overview
+
+**Modal** is a serverless GPU cloud. Key advantages over SSH-based platforms (vast.ai, remote servers):
+- **Zero config**: no SSH, no Docker, no port forwarding. Write Python → `modal run` → done.
+- **Auto scale-to-zero**: billing stops the instant your code finishes. No idle instances.
+- **Local-first**: run `modal run` from your laptop. Code, data, and results stay local; only the GPU function runs remotely.
+- **Reproducible environments**: dependencies declared in code via `modal.Image`, not system-level packages.
+
+**Best for**: Users without a local GPU who need to debug CUDA code, run small-scale tests, or iterate quickly on experiments. The $5 free tier (no card) is enough for code debugging; $30 (with card) covers most small-scale experiment runs.
+
+**Trade-off**: Modal costs more per GPU-hour than vast.ai or Lightning for some GPU tiers, but eliminates setup time and idle billing, often making it cheaper for short/medium workloads. For long training runs (>4 hours), consider vast.ai for lower $/hr.
+
+## Authentication
+
+```bash
+pip install modal
+modal setup          # Opens browser login, writes token to ~/.modal.toml
+# Verify:
+modal run -q 'print("ok")'
+```
+
+- Sign up: https://modal.com (GitHub/Google login)
+- Free (no card): **$5/month** — enough for quick tests
+- Free (with card): **$30/month** — bind a payment method at https://modal.com/settings for the full free tier. Set a **workspace spending limit** to prevent accidental overcharge (Settings → Usage → Spending Limit)
+- Academic: apply for $10k credits | Startups: apply for $25k credits
+- Secrets: `modal secret create huggingface-secret HF_TOKEN=hf_xxxxx`
+
+> **Recommended setup**: Bind a card to unlock $30/month, then immediately set a spending limit (e.g., $30) so you never exceed the free tier. Modal will pause your workloads when the limit is hit.
+>
+> **SECURITY WARNING**: Always bind your card and set spending limits directly on https://modal.com/settings in your browser. NEVER enter payment information, card numbers, or billing details through Codex, Claude Code, or any CLI tool. Only the official Modal website is safe for payment operations.
+
+## Pricing (source: modal.com/pricing, per-second billing)
+
+| GPU | $/sec | ≈$/hr | VRAM | Bandwidth GB/s | Free budget → hours |
+|---|---|---|---|---|---|
+| T4 | $0.000164 | $0.59 | 16GB | 300 | ~8.5 hr ($5) / 50.8 hr ($30) |
+| L4 | $0.000222 | $0.80 | 24GB | 300 | ~6.3 hr / 37.5 hr |
+| A10 | $0.000306 | $1.10 | 24GB | 600 | ~4.5 hr / 27.3 hr |
+| L40S | $0.000542 | $1.95 | 48GB | 864 | ~2.6 hr / 15.4 hr |
+| A100-40GB | $0.000583 | $2.10 | 40GB | 1555 | ~2.4 hr / 14.3 hr |
+| A100-80GB | $0.000694 | $2.50 | 80GB | 2039 | ~2.0 hr / 12.0 hr |
+| H100 | $0.001097 | $3.95 | 80GB | 3352 | ~1.3 hr / 7.6 hr |
+| H200 | $0.001261 | $4.54 | 141GB | 4800 | ~1.1 hr / 6.6 hr |
+| B200 | $0.001736 | $6.25 | 192GB | 8000 | ~0.8 hr / 4.8 hr |
+
+CPU: $0.047/core/hr | RAM: $0.008/GiB/hr (GPU typically 90%+ of total cost)
+
+## !! Cost Estimation Required !!
+
+Before EVERY run, estimate cost and show to user for confirmation.
+
+Key insights:
+- Inference bottleneck is **memory bandwidth**, not compute → high-bandwidth GPUs are often cheaper overall
+- 7-8B BF16 inference needs **~22GB VRAM** (weights 15G + KV cache 1G + overhead), T4 (16GB) insufficient
+- H100 is often **cheaper than L4** for benchmarks (11x faster but only 5x more expensive)
+
+### Cost Estimation Template (required before every run)
+
+```
+Cost estimate (Modal):
+  Model: [name] ([params], [precision])
+  VRAM: ~[X]GB (weights + KV cache + overhead)
+  GPU: [type] ([VRAM]GB, $[X]/sec = $[X]/hr, bandwidth [X] GB/s)
+  Estimate: ~[N] min, ~$[X]
+```
+
+### 7-8B BF16 Benchmark Cost Comparison
+
+| GPU | Speed tok/s | $/hr | 1000 samples x 200tok cost | Duration |
+|---|---|---|---|---|
+| **H100** | **224** | $3.95 | **$0.98** | **15 min** |
+| A100-40GB | 104 | $2.10 | $1.12 | 32 min |
+| L4 | 20 | $0.80 | $2.22 | 167 min |
+
+## Workflow
+
+### Step 1: Analyze Task → Estimate Cost → Choose GPU
+
+Same analysis as any GPU skill — determine VRAM needs from model size, pick GPU, estimate hours, calculate cost. See pricing table above.
+
+**VRAM Rules of Thumb:**
+| Model Size | FP16 VRAM | Recommended GPU |
+|---|---|---|
+| ≤3B | ~8GB | T4, L4 |
+| 7-8B | ~22GB | L4, A10, A100-40GB |
+| 13B | ~30GB | L40S, A100-40GB |
+| 30B | ~65GB | A100-80GB, H100 |
+| 70B | ~140GB | H100:2, H200 |
+
+### Step 2: Generate Modal Launcher
+
+Based on the task type, generate the appropriate launcher script.
+
+#### Pattern A: One-Shot GPU Function (training, evaluation, benchmark)
+
+The most common pattern for `run-experiment` integration. Wraps an existing training script:
+
+```python
+import modal
+
+app = modal.App("experiment-name")
+image = modal.Image.debian_slim(python_version="3.11").pip_install(
+    "torch", "transformers", "accelerate", "datasets", "wandb"
+)
+
+# Mount local project code into the container
+local_code = modal.Mount.from_local_dir(".", remote_path="/workspace")
+# Persistent volume for checkpoints and results
+volume = modal.Volume.from_name("experiment-results", create_if_missing=True)
+
+@app.function(
+    image=image,
+    gpu="A100-80GB",          # Chosen based on Step 1 analysis
+    mounts=[local_code],
+    volumes={"/results": volume},
+    timeout=3600 * 6,         # 6 hours max
+    secrets=[modal.Secret.from_name("wandb-secret")],  # Optional
+)
+def train():
+    import subprocess
+    subprocess.run(
+        ["python", "train.py", "--output_dir", "/results/run_001"],
+        cwd="/workspace",
+        check=True,
+    )
+    volume.commit()  # Persist results to volume
+
+@app.local_entrypoint()
+def main():
+    train.remote()
+    print("Training complete. Results saved to Modal volume 'experiment-results'.")
+```
+
+Run: `modal run launcher.py`
+
+#### Pattern B: Web API (persistent inference service)
+
+```python
+import modal
+
+app = modal.App("inference-api")
+image = modal.Image.debian_slim(python_version="3.11").pip_install(
+    "torch", "transformers", "accelerate"
+)
+
+@app.cls(image=image, gpu="L40S")
+@modal.concurrent(max_inputs=10)
+class InferenceAPI:
+    @modal.enter()
+    def load_model(self):
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+        self.tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B")
+        self.model = AutoModelForCausalLM.from_pretrained(
+            "meta-llama/Llama-3.2-1B", device_map="auto"
+        )
+
+    @modal.fastapi_endpoint(method="POST")
+    def generate(self, request: dict):
+        inputs = self.tokenizer(request.get("prompt", ""), return_tensors="pt").to("cuda")
+        outputs = self.model.generate(**inputs, max_new_tokens=256)
+        return {"text": self.tokenizer.decode(outputs[0], skip_special_tokens=True)}
+```
+
+Deploy: `modal deploy app.py`
+
+#### Pattern C: vLLM High-Performance Inference
+
+```python
+import modal, subprocess
+
+app = modal.App("vllm-server")
+image = modal.Image.debian_slim(python_version="3.11").pip_install("vllm")
+VOLUME = modal.Volume.from_name("model-cache", create_if_missing=True)
+MODEL = "Qwen/Qwen3-4B"
+
+@app.function(image=image, gpu="H100", volumes={"/models": VOLUME}, timeout=3600)
+@modal.concurrent(max_inputs=100)
+@modal.web_server(port=8000)
+def serve():
+    subprocess.Popen(["python", "-m", "vllm.entrypoints.openai.api_server",
+                      "--model", MODEL, "--download-dir", "/models", "--port", "8000"])
+```
+
+#### Pattern D: Batch Parallel (map over dataset)
+
+```python
+@app.function(image=image, gpu="T4", timeout=600)
+def process_item(item: dict) -> dict:
+    # ... process one item ...
+    return {"result": "processed"}
+
+@app.local_entrypoint()
+def main():
+    results = list(process_item.map([{"id": i} for i in range(1000)]))
+```
+
+#### Pattern E: LoRA Fine-Tuning
+
+```python
+@app.function(
+    image=image, gpu="A100-80GB", volumes={"/output": volume},
+    timeout=3600 * 6, secrets=[modal.Secret.from_name("huggingface-secret")],
+)
+def train():
+    # ... transformers + peft + trl training code ...
+    trainer.save_model("/output/final")
+    volume.commit()
+```
+
+#### Pattern F: Multi-GPU Distributed Training
+
+```python
+@app.function(image=image, gpu="H100:4", volumes={"/output": volume}, timeout=3600 * 12)
+def train_distributed():
+    import subprocess
+    subprocess.run(["accelerate", "launch", "--num_processes", "4",
+                    "--mixed_precision", "bf16", "train.py"], check=True)
+```
+
+### Step 3: Run
+
+```bash
+modal run launcher.py     # One-shot execution (most common for experiments)
+modal deploy app.py       # Persistent service deployment
+```
+
+### Step 4: Verify & Monitor
+
+```bash
+modal app list            # List running apps
+modal app logs <app-name> # Stream logs
+```
+
+### Step 5: Collect Results
+
+Results collection depends on the pattern used:
+
+**Volume-based** (recommended for training):
+```python
+# Download results from volume after run completes
+# Option A: In the launcher script, copy results to local mount before exit
+# Option B: Use modal volume commands
+modal volume ls experiment-results
+modal volume get experiment-results /run_001/results.json ./results/
+```
+
+**Stdout/return-based** (for evaluation/benchmarks):
+Results are printed to terminal or returned from the function — already local.
+
+### Step 6: Cleanup
+
+Modal auto-scales to zero — no manual instance destruction needed. But clean up unused resources:
+
+```bash
+modal app stop <app-name>     # Stop a deployed service
+modal volume rm <volume-name> # Delete a volume when done
+```
+
+## CLI Reference
+
+```bash
+modal run app.py          # Run once
+modal deploy app.py       # Deploy persistent service
+modal app logs <app>      # View logs
+modal app list            # List apps
+modal app stop <app>      # Stop
+modal volume ls           # List volumes
+modal volume get <vol> <remote> <local>  # Download from volume
+modal secret create NAME KEY=VALUE       # Create secret
+```
+
+## Key Tips
+
+- GPU fallback: `gpu=["H100", "A100-80GB", "L40S"]` — Modal tries each in order
+- Multi-GPU: `gpu="H100:4"` (up to 8 GPUs, cost scales linearly)
+- Volume: `modal.Volume.from_name("x", create_if_missing=True)` for persistent storage
+- `@modal.enter()` loads model once per container | `@modal.concurrent()` for concurrent requests
+- Long training: set `timeout=3600 * N` (default is 5 min)
+- Local code: `modal.Mount.from_local_dir(".", remote_path="/workspace")`
+- W&B integration: `secrets=[modal.Secret.from_name("wandb-secret")]` + `wandb.init()` in your script
+
+## Composing with Other Skills
+
+```
+/run-experiment "train model"       <- detects gpu: modal, calls /serverless-modal
+  -> /serverless-modal              <- analyzes task, generates launcher, runs
+  -> Results returned locally or to Modal Volume
+  -> No destroy step needed (auto scale-to-zero)
+
+/serverless-modal                   <- standalone: any Modal GPU workload
+/serverless-modal "deploy vLLM"     <- inference service deployment
+```
+
+## AGENTS.md Example
+
+```markdown
+## Modal
+- gpu: modal                 # tells run-experiment to use Modal serverless
+- modal_gpu: A100-80GB       # optional: override GPU selection (default: auto-select)
+- modal_timeout: 21600       # optional: max seconds (default: 6 hours)
+- modal_volume: my-results   # optional: named volume for results persistence
+```
+
+No SSH keys, no Docker images, no instance management needed. Just `pip install modal && modal setup`.
+
+> **Cost protection**: After `modal setup`, go to https://modal.com/settings in your browser (NEVER through CLI) → bind a payment method to unlock $30/month free tier (without card: only $5/month). Then set a **workspace spending limit** equal to your free tier amount — Modal will auto-pause workloads when the limit is reached, preventing any surprise charges.
+
+## Documentation
+
+- Docs: https://modal.com/docs/guide
+- GPU: https://modal.com/docs/guide/gpu
+- Pricing: https://modal.com/pricing
+- Examples: https://modal.com/docs/examples