diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..a2ce9ce --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,19 @@ +{ + "name": "gpcam", + "owner": { + "name": "CAMERA — Lawrence Berkeley National Laboratory", + "email": "MarcusNoack@lbl.gov", + "url": "https://gpcam.lbl.gov" + }, + "description": "gpCAM Claude Code skills for Gaussian process modeling, Bayesian optimization, and autonomous experiment design.", + "plugins": [ + { + "name": "gpcam", + "source": ".", + "description": "Skills that guide an AI assistant through designing autonomous experiments with gpCAM — kernels, acquisition, prior mean, noise, cost, gp2Scale, and multi-task GPs.", + "homepage": "https://gpcam.lbl.gov", + "category": "scientific-computing", + "keywords": ["gaussian-process", "bayesian-optimization", "autonomous-experiments", "gpcam", "scientific-computing"] + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..4e2722f --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "gpcam", + "description": "Skills that guide an AI assistant through designing autonomous experiments with gpCAM — custom kernels, acquisition functions, prior means, noise, cost, gp2Scale, and multi-task GPs.", + "author": { + "name": "CAMERA — Lawrence Berkeley National Laboratory", + "email": "MarcusNoack@lbl.gov", + "url": "https://gpcam.lbl.gov" + }, + "homepage": "https://gpcam.readthedocs.io", + "repository": "https://github.com/lbl-camera/gpCAM", + "license": "GPL-3.0", + "keywords": ["gaussian-process", "bayesian-optimization", "autonomous-experiments", "gpcam"] +} diff --git a/README.md b/README.md index efa95a5..2cffb73 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,20 @@ for i in range(100): gpCAM ships with a set of [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skills that guide an AI assistant through designing autonomous experiments — custom kernels, acquisition functions, noise models, and the full ask/tell/train loop. Experimentalists who want smart, autonomous data acquisition without deep knowledge of GP math or the gpCAM API can use these skills to design autonomous experiments. -When you clone this repo, the root `CLAUDE.md` and `skills/` directory are picked up automatically by Claude Code. Available skills: +### Installing the gpCAM marketplace in Claude Code + +The repo ships as a Claude Code [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Inside any Claude Code session, run: + +```text +/plugin marketplace add lbl-camera/gpCAM +/plugin install gpcam@gpcam +``` + +The first command registers this repo as a marketplace; the second installs the `gpcam` plugin from it, which bundles all of the skills below. After install, the skills are available to Claude in any project — no need to clone the repo locally. + +To update later, run `/plugin marketplace update gpcam`; to remove, `/plugin uninstall gpcam@gpcam`. + +### Available skills | Skill | Description | |-------|-------------| @@ -55,7 +68,11 @@ When you clone this repo, the root `CLAUDE.md` and `skills/` directory are picke | **gp2scale-advanced** | Large-scale experiments (>10k points) using sparse kernels and Dask distributed computing. | | **multi-task-advanced** | Multi-output / function-valued experiments with `fvGPOptimizer`. | -These skills are also compatible with other agentic platforms (e.g. [OpenClaw](https://openclaw.ai), or any harness that can read `SKILL.md` files) — point your assistant at the `skills/` directory. +Once installed, the skills activate automatically when you describe an experiment design problem to Claude, or you can invoke one explicitly (e.g. _"use the experiment-designer skill to set up an adaptive XRD scan"_). + +### Other agentic platforms + +The skills are also compatible with any harness that reads `SKILL.md` files (e.g. [OpenClaw](https://openclaw.ai)) — clone the repo and point your assistant at the `skills/` directory. When this repo is present in your working directory, Claude Code also picks up the root `CLAUDE.md` and `skills/` directory automatically, so the marketplace install is only needed for use outside the repo. ## Credits diff --git a/docs/source/_static/ai-agent-integration.png b/docs/source/_static/ai-agent-integration.png new file mode 100644 index 0000000..e9329dd Binary files /dev/null and b/docs/source/_static/ai-agent-integration.png differ diff --git a/docs/source/claude-skills.md b/docs/source/claude-skills.md new file mode 100644 index 0000000..393ce34 --- /dev/null +++ b/docs/source/claude-skills.md @@ -0,0 +1,113 @@ +# AI Agent Integration + +gpCAM ships with a set of [Claude Code](https://docs.anthropic.com/en/docs/claude-code) +skills that guide an AI assistant through designing autonomous experiments — +custom kernels, acquisition functions, noise and cost models, the full +`ask` / `tell` / `train` loop, and large-scale or multi-task setups. + +Experimentalists who want smart, autonomous data acquisition without deep +knowledge of GP math or the gpCAM API can let an AI assistant translate a +plain-English description of their measurement into a working gpCAM script. + +## Installing the marketplace in Claude Code + +The gpCAM repository is published as a Claude Code +[plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). +Inside any Claude Code session, run: + +```text +/plugin marketplace add lbl-camera/gpCAM +/plugin install gpcam@gpcam +``` + +The first command registers this repo as a marketplace and pulls its +`marketplace.json` manifest. The second installs the `gpcam` plugin from +that marketplace — a single plugin that bundles every skill listed below. +Once installed, the skills are available to Claude in any project on your +machine; you do **not** need to clone gpCAM locally. + +Useful follow-up commands: + +| Command | What it does | +|---|---| +| `/plugin marketplace list` | Show the marketplaces you've added. | +| `/plugin marketplace update gpcam` | Pull the latest skill versions. | +| `/plugin list` | Show installed plugins. | +| `/plugin uninstall gpcam@gpcam` | Remove the plugin. | + +## Using the skills + +Once the plugin is installed, Claude will activate the appropriate skill +automatically when you describe an experiment-design problem. For example: + +> *"I want to map the photoluminescence of a thin film over a 2-inch wafer. +> Each measurement takes 30 seconds, motor moves are slow in the X direction, +> and I have 4 hours of beam time."* + +…will trigger the **experiment-designer** skill (and pull in +**cost-functions** for the asymmetric motor cost). You can also invoke a +skill explicitly: + +> *"Use the kernel-designer skill to build a periodic + Matérn kernel for +> a temperature-dependent diffraction scan."* + +## Available skills + +```{list-table} +:header-rows: 1 +:widths: 25 75 + +* - Skill + - Description +* - **experiment-designer** + - End-to-end autonomous experiment design. Translates a scientist's + description of their measurement into a complete, runnable gpCAM script. +* - **kernel-designer** + - Design and compose custom kernel functions that encode domain knowledge + — smoothness, periodicity, symmetry, anisotropy, non-Euclidean inputs. +* - **acquisition-functions** + - Write custom acquisition functions that encode experimental priorities: + exploration vs exploitation, multi-objective targets, constraints, + cost-aware acquisition, UCB / LCB, probability of improvement. +* - **prior-mean-functions** + - Encode known physics or expected trends as prior mean functions, so the + GP regresses against a baseline rather than a flat zero prior. +* - **noise-functions** + - Model position-dependent, heteroscedastic, or count-rate-dependent noise + from detector characteristics. +* - **cost-functions** + - Account for motor travel time, settling, directional costs, sample + damage, beam time, and zone-based penalties. +* - **gp2scale-advanced** + - Large-scale experiments (>10k points up to millions) using sparse, + compactly-supported kernels and Dask distributed computing. +* - **multi-task-advanced** + - Multi-output, vector-valued, or function-valued experiments using + `fvGPOptimizer`. +``` + +## Using the skills outside Claude Code + +The skills are plain Markdown `SKILL.md` files and are compatible with any +agentic harness that can read them — for example +[OpenClaw](https://openclaw.ai). To use them outside Claude Code: + +1. Clone the gpCAM repository: + + ```bash + git clone https://github.com/lbl-camera/gpCAM.git + ``` + +2. Point your assistant at the `skills/` directory at the repo root. + +When the cloned repo is present in your working directory, Claude Code +also picks up the root `CLAUDE.md` and `skills/` directory automatically, +so the marketplace install is only needed for use *outside* the repo. + +## Source + +The marketplace manifest lives at +[`.claude-plugin/marketplace.json`](https://github.com/lbl-camera/gpCAM/blob/main/.claude-plugin/marketplace.json) +and the per-skill content under +[`skills/`](https://github.com/lbl-camera/gpCAM/tree/main/skills). +Contributions and new skills are welcome — open a pull request. diff --git a/docs/source/index.md b/docs/source/index.md index 39617ea..43594dc 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -38,6 +38,16 @@ examples/GPOptimizer_Optimization.ipynb ``` +```{toctree} +--- +hidden: true +maxdepth: 1 +caption: AI Agent Integration +--- +claude-skills.md +``` + + # gpCAM ```{div} centered-heading @@ -106,6 +116,20 @@ Software for the Novice and the Expert Simple uncertainty quantification and Bayesian optimization problems can be set up in minutes; the options for customization are endless. +```` +````` +````` {div} row +```` {div} col w-200 +![_static/ai-agent-integration.png](_static/ai-agent-integration.png) +```` + +```` {div} col +```{div} h3 +AI Agent Integration +``` + +gpCAM ships as a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin marketplace. AI assistants use the bundled skills to translate plain-English experiment descriptions into runnable gpCAM scripts — no GP expertise required. See [AI Agent Integration](claude-skills.md). + ```` ````` `````` diff --git a/skills/acquisition-functions/SKILL.md b/skills/acquisition-functions/SKILL.md index af2d031..996cb1a 100644 --- a/skills/acquisition-functions/SKILL.md +++ b/skills/acquisition-functions/SKILL.md @@ -1,3 +1,8 @@ +--- +name: acquisition-functions +description: Use when designing custom acquisition functions for gpCAM that encode experimental priorities — exploration vs exploitation balance, multi-objective targets, constrained search regions, cost-aware moves, UCB/LCB, or probability-of-improvement criteria. +--- + # Skill: gpCAM Acquisition Functions Design custom acquisition functions that control where gpCAM measures next. diff --git a/skills/cost-functions/SKILL.md b/skills/cost-functions/SKILL.md index c40bc0d..3e5e7e3 100644 --- a/skills/cost-functions/SKILL.md +++ b/skills/cost-functions/SKILL.md @@ -1,3 +1,8 @@ +--- +name: cost-functions +description: Use when modeling the real expense of moving between gpCAM measurement points — motor travel time, settling, directional costs, sample damage, beam time, or zone-based penalties. +--- + # Skill: gpCAM Cost Functions Design cost functions that account for the real expense of moving between measurement points — motor travel time, sample damage, beam time, etc. diff --git a/skills/experiment-designer/SKILL.md b/skills/experiment-designer/SKILL.md index b486415..5356aa2 100644 --- a/skills/experiment-designer/SKILL.md +++ b/skills/experiment-designer/SKILL.md @@ -1,3 +1,8 @@ +--- +name: experiment-designer +description: Use for end-to-end autonomous experiment design with gpCAM. Translates a scientist's description of their measurement into a complete, runnable gpCAM script — useful for replacing raster scans with adaptive sampling, peak-finding, or parameter optimization. +--- + # Skill: gpCAM Experiment Designer Design complete autonomous experiment scripts using gpCAM. You translate a scientist's description of their measurement into a runnable Python script. diff --git a/skills/gp2scale-advanced/SKILL.md b/skills/gp2scale-advanced/SKILL.md index 94222dc..bf5da4a 100644 --- a/skills/gp2scale-advanced/SKILL.md +++ b/skills/gp2scale-advanced/SKILL.md @@ -1,3 +1,8 @@ +--- +name: gp2scale-advanced +description: Use for large-scale gpCAM experiments (>10k points up to millions) using sparse compactly-supported kernels and Dask distributed computing for exact GP computation at scale. +--- + # Skill: gp2Scale — Large-Scale GPs Design experiments with tens of thousands to millions of data points using gpCAM's gp2Scale mode for exact GP computation at scale. diff --git a/skills/kernel-designer/SKILL.md b/skills/kernel-designer/SKILL.md index eda0ed0..4b04a2a 100644 --- a/skills/kernel-designer/SKILL.md +++ b/skills/kernel-designer/SKILL.md @@ -1,3 +1,8 @@ +--- +name: kernel-designer +description: Use when designing or composing custom kernel (covariance) functions for gpCAM that encode domain knowledge — smoothness, periodicity, symmetry, anisotropy, or non-Euclidean input spaces. +--- + # Skill: gpCAM Kernel Designer Design custom kernel (covariance) functions for gpCAM that encode domain knowledge about the experiment. diff --git a/skills/multi-task-advanced/SKILL.md b/skills/multi-task-advanced/SKILL.md index 54a9520..1c6e6bf 100644 --- a/skills/multi-task-advanced/SKILL.md +++ b/skills/multi-task-advanced/SKILL.md @@ -1,3 +1,8 @@ +--- +name: multi-task-advanced +description: Use for multi-output, vector-valued, or function-valued gpCAM experiments using fvGPOptimizer — useful when a single measurement returns multiple correlated quantities (e.g., spectra, multi-channel detectors). +--- + # Skill: Multi-Task GPs with fvGPOptimizer Design experiments with vector-valued or function-valued outputs using gpCAM's multi-task GP. diff --git a/skills/noise-functions/SKILL.md b/skills/noise-functions/SKILL.md index 32115bc..dbaae19 100644 --- a/skills/noise-functions/SKILL.md +++ b/skills/noise-functions/SKILL.md @@ -1,3 +1,8 @@ +--- +name: noise-functions +description: Use when modeling position-dependent, heteroscedastic, or otherwise structured noise in gpCAM — e.g., detector characteristics, count-rate-dependent variance, or non-uniform measurement uncertainty. +--- + # Skill: gpCAM Noise Functions Design custom noise models for experiments with non-uniform or structured noise. diff --git a/skills/prior-mean-functions/SKILL.md b/skills/prior-mean-functions/SKILL.md index cb6bab7..abcc514 100644 --- a/skills/prior-mean-functions/SKILL.md +++ b/skills/prior-mean-functions/SKILL.md @@ -1,3 +1,8 @@ +--- +name: prior-mean-functions +description: Use when encoding known physics, theoretical models, or expected trends as prior mean functions for gpCAM — useful when there's a baseline expectation the GP should regress against rather than a flat zero prior. +--- + # Skill: gpCAM Prior Mean Functions Design prior mean functions that encode known physics or expected trends.