@synsci/cli-darwin-x64 1.1.59 → 1.1.60

package/bin/skills/modal/SKILL.md

@@ -1,341 +1,382 @@
 ---
 name: modal-serverless-gpu
-description: Serverless GPU cloud platform for running ML workloads. Use when you need on-demand GPU access without infrastructure management, deploying ML models as APIs, or running batch jobs with automatic scaling.
-version: 1.0.0
+description: Serverless GPU cloud platform for ML workloads — inference serving, batch processing, training, web endpoints, sandboxes, and scheduled jobs. Use when you need on-demand GPUs without infrastructure management, deploying models as auto-scaling APIs, running batch jobs, or executing untrusted code in sandboxes.
+version: 2.0.0
 author: Synthetic Sciences
 license: MIT
-tags: [Infrastructure, Serverless, GPU, Cloud, Deployment, Modal]
-dependencies: [modal>=0.64.0]
+tags: [Infrastructure, Serverless, GPU, Cloud, Deployment, Modal, Inference, Training, Sandboxes, Web Endpoints]
+dependencies: [modal>=0.73.0]
 ---
 
 # Modal Serverless GPU
 
-Comprehensive guide to running ML workloads on Modal's serverless GPU cloud platform.
+Modal is a serverless GPU cloud platform. Everything is Python code — no YAML, no Docker, no Kubernetes. Pay per second, scale to zero, scale to hundreds of GPUs instantly.
 
-## When to use Modal
+This skill provides the decision framework, GPU guide, API reference, and a catalog of 50+ production-ready examples from Modal's official library. For detailed implementations, refer to the example catalog and reference docs below.
 
-**Use Modal when:**
-- Running GPU-intensive ML workloads without managing infrastructure
-- Deploying ML models as auto-scaling APIs
-- Running batch processing jobs (training, inference, data processing)
-- Need pay-per-second GPU pricing without idle costs
-- Prototyping ML applications quickly
-- Running scheduled jobs (cron-like workloads)
+## When to Use Modal
 
-**Key features:**
-- **Serverless GPUs**: T4, L4, A10G, L40S, A100, H100, H200, B200 on-demand
-- **Python-native**: Define infrastructure in Python code, no YAML
-- **Auto-scaling**: Scale to zero, scale to 100+ GPUs instantly
-- **Sub-second cold starts**: Rust-based infrastructure for fast container launches
-- **Container caching**: Image layers cached for rapid iteration
-- **Web endpoints**: Deploy functions as REST APIs with zero-downtime updates
+**Modal is the RIGHT choice for:**
+
+| Workload | Why Modal |
+|----------|-----------|
+| **Inference serving** | Auto-scaling endpoints, zero-downtime deploys, sub-second cold starts |
+| **Batch processing** | Fan out to 100+ GPUs with `.map()`, pay only for compute time |
+| **Web endpoints / APIs** | FastAPI/ASGI/WSGI support, custom domains, streaming |
+| **Sandbox execution** | Run untrusted code safely, build coding agents, code interpreters |
+| **Scheduled jobs** | Cron/periodic with `modal.Cron` and `modal.Period` |
+| **Full-parameter training** | Multi-GPU (up to 8), multi-node clusters (beta) |
+| **Custom architectures** | Full control over container images, any framework |
+| **Data pipelines** | Parallel processing, S3 mounts, Volume storage |
 
 **Use alternatives instead:**
-- **RunPod**: For longer-running pods with persistent state
-- **Lambda Labs**: For reserved GPU instances
-- **SkyPilot**: For multi-cloud orchestration and cost optimization
-- **Kubernetes**: For complex multi-service architectures
 
-## Quick start
+| Need | Use Instead |
+|------|-------------|
+| Managed LoRA fine-tuning (no infra) | **Tinker** |
+| Hosted RL / agentic post-training | **Prime Intellect Lab** |
+| Reserved dedicated instances | **Lambda Labs** |
+| Multi-cloud cost optimization | **SkyPilot** |
+| Long-running persistent pods | **RunPod** |
+
+## Credential Setup (synsc)
 
-### Installation
+Credentials are auto-injected via SynSci. Verify before running Modal workloads:
 
 ```bash
-pip install modal
-modal setup  # Opens browser for authentication
+# Check credentials are set (NEVER echo the actual values)
+[ -n "$MODAL_TOKEN_ID" ] && echo "MODAL_TOKEN_ID set" || echo "NOT SET"
+[ -n "$MODAL_TOKEN_SECRET" ] && echo "MODAL_TOKEN_SECRET set" || echo "NOT SET"
 ```
 
-### Hello World with GPU
+**IMPORTANT**: Always rely on `MODAL_TOKEN_ID`/`MODAL_TOKEN_SECRET` env vars. Do NOT read from `~/.modal.toml`.
 
-```python
-import modal
+If Modal CLI isn't installed: `pip install modal` (no `modal setup` needed — env vars handle auth).
 
-app = modal.App("hello-gpu")
+## Quick Reference
 
-@app.function(gpu="T4")
-def gpu_info():
-    import subprocess
-    return subprocess.run(["nvidia-smi"], capture_output=True, text=True).stdout
+| Topic | Reference |
+|-------|-----------|
+| Example Catalog (50+ examples) | [Examples Catalog](references/examples-catalog.md) |
+| Advanced Patterns & synsc Integration | [Advanced Patterns](references/advanced-patterns.md) |
+| Troubleshooting | [Troubleshooting](references/troubleshooting.md) |
 
-@app.local_entrypoint()
-def main():
-    print(gpu_info.remote())
-```
-
-Run: `modal run hello_gpu.py`
-
-### Basic inference endpoint
+## Execution Modes
 
+| Command | When to Use |
+|---------|-------------|
+| `modal run script.py` | One-off jobs: training, batch processing, data pipelines |
+| `modal serve script.py` | Development: live reload on code changes, test endpoints locally |
+| `modal deploy script.py` | Production: persistent endpoints, scheduled jobs, always-on services |
+
+## GPU Selection Guide
+
+| GPU | VRAM | $/hr (approx) | Best For |
+|-----|------|----------------|----------|
+| `T4` | 16GB | ~$0.59 | Budget inference, small models (<7B quantized) |
+| `L4` | 24GB | ~$0.73 | Inference, Ada Lovelace architecture |
+| `A10G` | 24GB | ~$1.10 | Training/inference, 3.3x faster than T4 |
+| `L40S` | 48GB | ~$1.65 | **Best cost/perf for inference** (7B-13B FP16) |
+| `A100-40GB` | 40GB | ~$3.15 | Large model training |
+| `A100-80GB` | 80GB | ~$4.05 | Very large models, DeepSpeed |
+| `H100` | 80GB | ~$4.25 | Fastest training, FP8 + Transformer Engine |
+| `H200` | 141GB | ~$4.95 | Largest VRAM, 4.8TB/s bandwidth |
+| `B200` | 192GB | Latest | Blackwell architecture, newest |
+
+**GPU specification patterns:**
 ```python
-import modal
-
-app = modal.App("text-generation")
-image = modal.Image.debian_slim().pip_install("transformers", "torch", "accelerate")
-
-@app.cls(gpu="A10G", image=image)
-class TextGenerator:
-    @modal.enter()
-    def load_model(self):
-        from transformers import pipeline
-        self.pipe = pipeline("text-generation", model="gpt2", device=0)
-
-    @modal.method()
-    def generate(self, prompt: str) -> str:
-        return self.pipe(prompt, max_length=100)[0]["generated_text"]
-
-@app.local_entrypoint()
-def main():
-    print(TextGenerator().generate.remote("Hello, world"))
+@app.function(gpu="A100")           # Single GPU
+@app.function(gpu="A100-80GB")      # Specific memory variant
+@app.function(gpu="H100:4")         # Multi-GPU (up to 8)
+@app.function(gpu=["H100", "A100"]) # Fallback chain (try in order)
+@app.function(gpu="any")            # Any available GPU
 ```
 
-## Core concepts
-
-### Key components
-
-| Component | Purpose |
+**Recommendations by task:**
+
+| Task | GPU | Config |
+|------|-----|--------|
+| Serve 7B model (FP16) | `L40S` or `A10G` | Single GPU |
+| Serve 70B model (AWQ/GPTQ) | `A100-80GB` or `H100` | Single GPU |
+| Serve 70B model (FP16) | `H100:4` or `A100-80GB:4` | Multi-GPU |
+| LoRA fine-tune 7B | `A100-40GB` | Single GPU |
+| Full fine-tune 7B | `A100-80GB:4` | Multi-GPU |
+| Full fine-tune 70B | `H100:8` or multi-node | Multi-GPU/node |
+| Batch inference | `L40S` or `A100` | `.map()` fan-out |
+| Embedding generation | `T4` or `L4` | `.map()` fan-out |
+
+## Core API Quick Reference
+
+### Key Classes
+
+| Class | Purpose | Key Methods |
+|-------|---------|-------------|
+| `modal.App` | Container for functions/resources | `.function()`, `.cls()`, `.local_entrypoint()` |
+| `modal.Image` | Container image definition | `.debian_slim()`, `.uv_pip_install()`, `.pip_install()`, `.from_registry()`, `.add_local_dir()`, `.run_commands()`, `.env()` |
+| `modal.Volume` | Persistent distributed filesystem (2.5 GB/s) | `.from_name()`, `.commit()`, `.reload()` |
+| `modal.Secret` | Secure credential injection | `.from_name()`, `.from_dict()`, `.from_dotenv()` |
+| `modal.Dict` | Distributed key-value store | `.from_name()`, `.put()`, `.get()`, `.pop()` |
+| `modal.Queue` | Distributed FIFO queue | `.from_name()`, `.put()`, `.get()` |
+| `modal.Sandbox` | Isolated code execution container | `.create()`, `.exec()`, `.terminate()`, snapshot support |
+| `modal.Cls` | Class-based serverless functions | Used via `@app.cls()` decorator |
+| `modal.Function` | Serverless function handle | `.remote()`, `.local()`, `.map()`, `.starmap()`, `.lookup()` |
+| `modal.CloudBucketMount` | Mount S3/GCS buckets as filesystem | Direct bucket access |
+| `modal.Tunnel` | Network tunnel to containers | SSH, HTTP access |
+| `modal.Proxy` | Network proxy (beta) | Custom networking |
+
+### Key Decorators
+
+| Decorator | Purpose |
 |-----------|---------|
-| `App` | Container for functions and resources |
-| `Function` | Serverless function with compute specs |
-| `Cls` | Class-based functions with lifecycle hooks |
-| `Image` | Container image definition |
-| `Volume` | Persistent storage for models/data |
-| `Secret` | Secure credential storage |
-
-### Execution modes
-
-| Command | Description |
-|---------|-------------|
-| `modal run script.py` | Execute and exit |
-| `modal serve script.py` | Development with live reload |
-| `modal deploy script.py` | Persistent cloud deployment |
-
-## GPU configuration
-
-### Available GPUs
-
-| GPU | VRAM | Best For |
-|-----|------|----------|
-| `T4` | 16GB | Budget inference, small models |
-| `L4` | 24GB | Inference, Ada Lovelace arch |
-| `A10G` | 24GB | Training/inference, 3.3x faster than T4 |
-| `L40S` | 48GB | Recommended for inference (best cost/perf) |
-| `A100-40GB` | 40GB | Large model training |
-| `A100-80GB` | 80GB | Very large models |
-| `H100` | 80GB | Fastest, FP8 + Transformer Engine |
-| `H200` | 141GB | Auto-upgrade from H100, 4.8TB/s bandwidth |
-| `B200` | Latest | Blackwell architecture |
-
-### GPU specification patterns
+| `@app.function()` | Define a serverless function |
+| `@app.cls()` | Define a serverless class |
+| `@modal.method()` | Mark class method as remotely callable |
+| `@modal.enter()` | Run once at container startup (model loading) |
+| `@modal.exit()` | Run at container shutdown (cleanup) |
+| `@modal.parameter()` | Typed class parameter |
+| `@modal.fastapi_endpoint()` | Expose function as FastAPI endpoint |
+| `@modal.asgi_app()` | Expose full ASGI app (FastAPI/Starlette) |
+| `@modal.wsgi_app()` | Expose WSGI app (Django/Flask) |
+| `@modal.web_server(port)` | Expose arbitrary HTTP server |
+| `@modal.batched()` | Dynamic input batching |
+| `@modal.concurrent()` | Input concurrency control |
+
+### Scheduling
+
+| Type | Syntax |
+|------|--------|
+| Cron | `schedule=modal.Cron("0 0 * * *")` (always UTC) |
+| Periodic | `schedule=modal.Period(hours=1)` |
+
+## Essential Patterns
+
+### Pattern 1: Model Inference Service
 
 ```python
-# Single GPU
-@app.function(gpu="A100")
-
-# Specific memory variant
-@app.function(gpu="A100-80GB")
-
-# Multiple GPUs (up to 8)
-@app.function(gpu="H100:4")
-
-# GPU with fallbacks
-@app.function(gpu=["H100", "A100", "L40S"])
-
-# Any available GPU
-@app.function(gpu="any")
-```
-
-## Container images
+import modal
 
-```python
-# Basic image with pip
-image = modal.Image.debian_slim(python_version="3.11").pip_install(
-    "torch==2.1.0", "transformers==4.36.0", "accelerate"
+app = modal.App("inference")
+image = modal.Image.debian_slim(python_version="3.11").uv_pip_install(
+    "torch", "transformers", "accelerate"
 )
-
-# From CUDA base
-image = modal.Image.from_registry(
-    "nvidia/cuda:12.1.0-cudnn8-devel-ubuntu22.04",
-    add_python="3.11"
-).pip_install("torch", "transformers")
-
-# With system packages
-image = modal.Image.debian_slim().apt_install("git", "ffmpeg").pip_install("whisper")
-```
-
-## Persistent storage
-
-```python
 volume = modal.Volume.from_name("model-cache", create_if_missing=True)
 
-@app.function(gpu="A10G", volumes={"/models": volume})
-def load_model():
-    import os
-    model_path = "/models/llama-7b"
-    if not os.path.exists(model_path):
-        model = download_model()
-        model.save_pretrained(model_path)
-        volume.commit()  # Persist changes
-    return load_from_path(model_path)
-```
-
-## Web endpoints
-
-### FastAPI endpoint decorator
+@app.cls(gpu="L40S", image=image, volumes={"/models": volume},
+         container_idle_timeout=300)
+class InferenceService:
+    @modal.enter()
+    def load(self):
+        from transformers import pipeline
+        self.pipe = pipeline("text-generation", model="/models/my-model", device=0)
 
-```python
-@app.function()
-@modal.fastapi_endpoint(method="POST")
-def predict(text: str) -> dict:
-    return {"result": model.predict(text)}
+    @modal.method()
+    def generate(self, prompt: str) -> str:
+        return self.pipe(prompt, max_length=512)[0]["generated_text"]
 ```
 
-### Full ASGI app
+### Pattern 2: vLLM Deployment (see Modal example: `llm_inference`)
 
 ```python
-from fastapi import FastAPI
-web_app = FastAPI()
+import modal
 
-@web_app.post("/predict")
-async def predict(text: str):
-    return {"result": await model.predict.remote.aio(text)}
+app = modal.App("vllm-server")
+image = modal.Image.debian_slim(python_version="3.11").uv_pip_install("vllm")
+volume = modal.Volume.from_name("model-weights", create_if_missing=True)
 
-@app.function()
+@app.function(gpu="H100", image=image, volumes={"/models": volume},
+              container_idle_timeout=600, timeout=3600)
 @modal.asgi_app()
-def fastapi_app():
-    return web_app
+def serve():
+    # See Modal example `llm_inference` for the full implementation
+    ...
 ```
 
-### Web endpoint types
-
-| Decorator | Use Case |
-|-----------|----------|
-| `@modal.fastapi_endpoint()` | Simple function → API |
-| `@modal.asgi_app()` | Full FastAPI/Starlette apps |
-| `@modal.wsgi_app()` | Django/Flask apps |
-| `@modal.web_server(port)` | Arbitrary HTTP servers |
-
-## Dynamic batching
+### Pattern 3: Batch Processing with Fan-Out
 
 ```python
-@app.function()
-@modal.batched(max_batch_size=32, wait_ms=100)
-async def batch_predict(inputs: list[str]) -> list[dict]:
-    # Inputs automatically batched
-    return model.batch_predict(inputs)
-```
-
-## Secrets management
-
-```bash
-# Create secret
-modal secret create huggingface HF_TOKEN=hf_xxx
-```
-
-```python
-@app.function(secrets=[modal.Secret.from_name("huggingface")])
-def download_model():
-    import os
-    token = os.environ["HF_TOKEN"]
-```
-
-## Scheduling
-
-```python
-@app.function(schedule=modal.Cron("0 0 * * *"))  # Daily midnight
-def daily_job():
-    pass
+@app.function(gpu="T4")
+def process_item(item):
+    return expensive_computation(item)
 
-@app.function(schedule=modal.Period(hours=1))
-def hourly_job():
-    pass
+@app.local_entrypoint()
+def main():
+    items = list(range(10000))
+    results = list(process_item.map(items))  # Fan out to parallel GPUs
 ```
 
-## Performance optimization
-
-### Cold start mitigation
+### Pattern 4: Container Image (use uv for speed)
 
 ```python
-@app.function(
-    container_idle_timeout=300,  # Keep warm 5 min
-    allow_concurrent_inputs=10,  # Handle concurrent requests
+# Prefer uv_pip_install — 10-50x faster than pip_install
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .uv_pip_install("torch", "transformers", "accelerate", "vllm")
+    .add_local_dir("./src", "/app/src")  # Add local code
+    .env({"HF_HOME": "/models"})          # Set env vars
 )
-def inference():
-    pass
-```
-
-### Model loading best practices
-
-```python
-@app.cls(gpu="A100")
-class Model:
-    @modal.enter()  # Run once at container start
-    def load(self):
-        self.model = load_model()  # Load during warm-up
-
-    @modal.method()
-    def predict(self, x):
-        return self.model(x)
 ```
 
-## Parallel processing
+### Pattern 5: Sandbox (Code Execution)
 
 ```python
-@app.function()
-def process_item(item):
-    return expensive_computation(item)
-
-@app.function()
-def run_parallel():
-    items = list(range(1000))
-    # Fan out to parallel containers
-    results = list(process_item.map(items))
-    return results
+sandbox = modal.Sandbox.create(app=app, image=image, gpu="T4", timeout=300)
+process = sandbox.exec("python", "-c", "print('Hello from sandbox')")
+print(process.stdout.read())
+sandbox.terminate()
 ```
 
-## Common configuration
+## Example Catalog (Quick Lookup)
+
+Modal's official example library contains production-ready implementations. Find the right example for your task below, then refer to [Examples Catalog](references/examples-catalog.md) for expanded descriptions and implementation notes.
+
+### LLM Inference & Serving
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `llm_inference` | Deploy OpenAI-compatible LLM service | vLLM, H100, streaming, OpenAI API |
+| `very_large_models` | Deploy really big LLMs (DeepSeek V3, Kimi-K2) | SGLang, multi-GPU (H200:4-8), 100B+ params |
+| `ministral3_inference` | 10x cold start reduction with snapshots | Memory snapshots, fast startup |
+| `vllm_throughput` | Optimize tokens/sec batch processing | vLLM, ~30K input tok/s per H100 |
+| `sglang_low_latency` | Low-latency inference with SGLang | SGLang, speculative decoding, EAGLE-3 |
+| `llama_cpp` | Run GGUF models with llama.cpp | CPU/GPU inference, quantized models |
+| `trtllm_latency` | Low-latency with TensorRT-LLM | TensorRT optimization |
+| `trtllm_throughput` | High-throughput with TensorRT-LLM | Batch TensorRT inference |
+
+### Training & Fine-Tuning
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `grpo_verl` | GRPO math training with verl | RL training, math reasoning |
+| `grpo_trl` | GRPO coding training with TRL | RL training, code generation |
+| `unsloth_finetune` | Efficient fine-tuning with Unsloth | LoRA, 2x speed, memory efficient |
+| `hp_sweep_gpt` | Train SLM with hyperparameter search | Grid search, early stopping |
+| `long-training` | Long, resumable training jobs | Checkpointing, Volume, resume |
+| `llm-finetuning` | Full LLM fine-tuning pipeline | End-to-end training |
+| `flan_t5_finetune` | Fine-tune Flan-T5 | Seq2seq fine-tuning |
+| `diffusers_lora_finetune` | Fine-tune Flux with LoRA | Image generation LoRA |
+
+### Multimodal & Vision
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `flux` | Serve diffusion models with torch.compile | Image generation, compilation |
+| `text_to_image` | Stable Diffusion CLI/API/UI | Text-to-image, Gradio |
+| `image_to_image` | Edit images with Flux Kontext | Image-to-image |
+| `image_to_video` | Bring images to life with LTX-Video | Video generation |
+| `ltx` | Generate video with LTX-Video | Text-to-video |
+| `finetune_yolo` | Fine-tune & serve YOLO | Object detection |
+| `segment_anything` | Segment Anything Model | Image segmentation |
+| `comfyapp` | Run Flux on ComfyUI as API | ComfyUI, workflow API |
+| `blender_video` | 3D render farm with Blender | 3D rendering, parallelism |
+
+### Audio & Speech
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `llm-voice-chat` | Voice chat with LLMs | Real-time voice, WebSocket |
+| `streaming_kyutai_stt` | Transcribe speech with Kyutai STT | Streaming STT, low latency |
+| `music-video-gen` | Star in custom music videos | Multi-model pipeline |
+| `generate_music` | Make music with ACE-Step | Music generation |
+| `chatterbox_tts` | Generate speech with Chatterbox | TTS |
+| `batched_whisper` | High-throughput Whisper transcription | Batch ASR, Whisper |
+| `fine_tune_asr` | Fine-tune Whisper for new words | ASR fine-tuning |
+
+### Sandboxes & Code Execution
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `agent` | Sandbox a LangGraph agent's code | LangGraph, secure GPU sandbox |
+| `opencode_server` | Run background coding agent (OpenCode) | Coding agent, sandbox |
+| `modal-vibe` | Deploy vibe coding at scale | React + LLM + Sandboxes |
+| `safe_code_execution` | Run Node.js, Ruby, and more in sandbox | Multi-language, sandbox |
+| `simple_code_interpreter` | Stateful code interpreter | Jupyter-like, sandbox |
+| `jupyter_sandbox` | Sandboxed Jupyter notebook | Jupyter, sandbox |
+| `anthropic_computer_use` | Control computer with LLM | Computer use, sandbox |
+
+### RAG & Embeddings
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `chat_with_pdf_vision` | RAG Chat with PDFs | PDF Q&A, vision |
+| `amazon_embeddings` | Embed millions of docs with TEI | High-throughput embeddings |
+| `mongodb-search` | Satellite images to vectors + MongoDB | Image embeddings, geo search |
+| `potus_speech_qanda` | RAG Q&A chatbot with OpenAI | RAG, OpenAI |
+
+### Web Apps & Endpoints
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `basic_web` | Serving web endpoints | FastAPI, ASGI |
+| `serve_streamlit` | Deploy Streamlit apps | Streamlit |
+| `mcp_server_stateless` | Deploy stateless MCP with FastMCP | MCP, tool serving |
+| `webrtc_yolo` | Serverless WebRTC with YOLO | WebRTC, real-time |
+| `fastrtc_flip_webcam` | WebRTC quickstart with FastRTC | FastRTC |
+| `webscraper` | Simple web scraper | Scraping, parallelism |
+
+### Data & Infrastructure
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `s3_bucket_mount` | Parallel Parquet processing on S3 | CloudBucketMount, S3 |
+| `cloud_bucket_mount_loras` | LoRA playground with S3 + Gradio | LoRA management, S3 |
+| `dbt_duckdb` | Data warehouse with DuckDB + DBT | Analytics, data warehouse |
+| `doc_ocr_jobs` | Document OCR job queue | Job queue, OCR |
+| `doc_ocr_webapp` | Document OCR web app | Web app, OCR |
+| `hackernews_alerts` | Hacker News Slackbot | Scheduled jobs, Slack |
+| `discord_bot` | Deploy a Discord bot | Discord, bot |
+| `db_to_sheet` | Sync DB to Google Sheets | Google Sheets, ETL |
+| `cron_datasette` | Publish data with SQLite + Datasette | Data exploration |
+| `algolia_indexer` | Build docsearch with Algolia | Documentation search |
+
+### Computational Biology
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| `chai1` | Fold proteins with Chai-1 | Protein folding |
+| `boltz_predict` | Fold proteins with Boltz-2 | Protein structure |
+| `esm3` | ESM3 protein model | Protein language model |
+
+## Common Configuration Reference
 
 ```python
 @app.function(
-    gpu="A100",
-    memory=32768,              # 32GB RAM
-    cpu=4,                     # 4 CPU cores
-    timeout=3600,              # 1 hour max
-    container_idle_timeout=120,# Keep warm 2 min
-    retries=3,                 # Retry on failure
-    concurrency_limit=10,      # Max concurrent containers
+    gpu="A100",                        # GPU type (see selection guide)
+    memory=32768,                      # RAM in MB
+    cpu=4,                             # CPU cores
+    timeout=3600,                      # Max execution time (seconds)
+    container_idle_timeout=120,        # Keep container warm (seconds)
+    retries=modal.Retries(max_retries=3, backoff_coefficient=2.0),
+    concurrency_limit=10,              # Max concurrent containers
+    allow_concurrent_inputs=20,        # Requests per container
+    keep_warm=1,                       # Min warm containers (costs money)
+    volumes={"/data": volume},         # Mount volumes
+    secrets=[modal.Secret.from_name("my-secret")],
+    image=image,                       # Custom container image
+    schedule=modal.Cron("0 0 * * *"), # Cron schedule (UTC)
 )
 def my_function():
     pass
 ```
 
-## Debugging
-
-```python
-# Test locally
-if __name__ == "__main__":
-    result = my_function.local()
-
-# View logs
-# modal app logs my-app
-```
-
-## Common issues
-
-| Issue | Solution |
-|-------|----------|
-| Cold start latency | Increase `container_idle_timeout`, use `@modal.enter()` |
-| GPU OOM | Use larger GPU (`A100-80GB`), enable gradient checkpointing |
-| Image build fails | Pin dependency versions, check CUDA compatibility |
-| Timeout errors | Increase `timeout`, add checkpointing |
-
-## References
-
-- **[Advanced Usage](references/advanced-usage.md)** - Multi-GPU, distributed training, cost optimization
-- **[Troubleshooting](references/troubleshooting.md)** - Common issues and solutions
-
-## Resources
-
-- **Documentation**: https://modal.com/docs
-- **Examples**: https://github.com/modal-labs/modal-examples
-- **Pricing**: https://modal.com/pricing
-- **Discord**: https://discord.gg/modal
+## Common Issues Quick-Fix
+
+| Issue | Fix |
+|-------|-----|
+| Cold start slow | Use `@modal.enter()` for model loading, increase `container_idle_timeout`, use memory snapshots |
+| GPU OOM | Use larger GPU, enable gradient checkpointing, use mixed precision (bf16) |
+| Image build fails | Pin versions, use `uv_pip_install`, use multi-stage builds |
+| Timeout errors | Increase `timeout`, add checkpointing for long jobs |
+| Volume changes lost | Call `volume.commit()` after writes |
+| Stale volume data | Call `volume.reload()` before reads |
+| Cron not firing | Cron is always UTC, must `modal deploy` (not `modal run`) |
+| 502 on endpoint | Increase timeout, check memory, use streaming for long responses |
+| Credentials fail | Verify `MODAL_TOKEN_ID`/`MODAL_TOKEN_SECRET` env vars are set |
+
+## Implementation Workflow
+
+When implementing a Modal workload:
+1. Check the example catalog above to find the closest matching example
+2. Load the [Examples Catalog](references/examples-catalog.md) for expanded implementation notes
+3. Refer to Modal's docs at https://modal.com/docs/examples for full source code
+4. Adapt for your use case using synsc credentials (`MODAL_TOKEN_ID`/`MODAL_TOKEN_SECRET`)
+5. After job completes, report usage via `SynSci.reportUsage()` with `service="modal"`