PIASO-for-agents

# PIASO-for-agents

**Make the [PIASO](https://piaso.org) single-cell omics ecosystem first-class for any
coding agent — Claude Code, Cursor, Copilot, Codex, Windsurf, Cline, Aider — from one
canonical, agent-neutral knowledge pack.**

Maintained by **[The Fishell Laboratory](https://fishelllab.hms.harvard.edu)** (Harvard
Medical School / Broad Institute). Every agent-specific format (Claude skill, Cursor rules, `AGENTS.md`,
`llms.txt`, MCP server) is a **generated artifact** built from `canonical/` — never a
hand-maintained copy. A CI drift check (`python build.py --check`) fails the build if any
`dist/` artifact is out of sync with `canonical/`, and the code-block test suite runs every
canonical block against the **pinned component versions** on every push, nightly, and on
component releases, so the guidance cannot silently rot.

**Hub v0.2.1 · piaso-mcp 0.1.1 — tested against piaso-tools 1.2.6 · cosg 1.2.0 ·
cytome 0.3.6 · laris 0.14.0 · emergene 1.0.2 · cytorete 0.1.1 · COSGR 1.0.0 · cytome (R) 0.1.0 (2026-09-29).**

## The ecosystem

Independently-installable packages under [github.com/genecell](https://github.com/genecell), in
four layers. Dependencies run one way (`cytorete → piaso-tools → cosg + cytome`; `laris → cosg`),
and `pip install piaso-tools` already brings COSG and cytome.

| Layer | Component | Package | Language | Role |
|---|---|---|---|---|
| Analysis | [PIASO](https://github.com/genecell/PIASO) | `piaso-tools` | Python + Rust | Self-contained pipeline — reading 10x data, QC, doublets, **INFOG**, SVD / **GDR**, Leiden / UMAP, **PIASOscore**, annotation, **SCALAR**, PIASOmarkerDB client, plotting, `piaso.data`. **No scanpy required.** |
| Storage | [cytome](https://github.com/genecell/cytome) | `cytome` | Python | Single-file SQLite `.cytome`: matrices, SQL-queryable cell/gene tables, embeddings, graphs, fragments, tissue images, provenance — what every component streams from |
| | [cytome (R)](https://github.com/genecell/cytome-r) | `cytome` (r-universe) | R | Read / write / stream the same file into Seurat or SingleCellExperiment, no Python |
| Methods | [COSG](https://github.com/genecell/COSG) | `cosg` | Python | Marker genes by cosine specificity — analytic p-values, GPU, batch-aware, streams from cytome |
| | [COSGR](https://github.com/genecell/COSGR) | `COSG` (r-universe / conda-forge) | R | COSG for Seurat / SingleCellExperiment |
| | [LARIS](https://github.com/genecell/LARIS) | `laris` | Python | Ligand–receptor interaction in **spatial** transcriptomics; exact p-values; cross-condition comparison |
| | [Emergene](https://github.com/genecell/Emergene) | `emergene` | Python | Individual-cell differential expression across conditions |
| | [cytorete](https://github.com/genecell/cytorete) | `cytorete` | Python | Cell-type-resolved gene regulatory networks (regulons) on the PIASO stack |
| Data | [PIASO-data](https://github.com/genecell/PIASO-data) | — | data | Tutorial datasets (Zenodo, incl. five `.cytome` atlases) + genome references; registry read by `piaso.data` |

Each component is **independently installable** — a COSG-only, cytome-only or LARIS-only user is
a first-class citizen, and every `canonical/components/*.md` assumes nothing else is installed.
The hub's unique value is documenting how the components **compose**, and the cross-component
choices no single repo can make: **SCALAR vs LARIS** (dissociated vs spatial ligand–receptor —
same CellChatDB either way), **AnnData vs `.cytome`** (in memory vs streamed — same function
calls), **COSG vs cytorete** (marker genes vs the TFs that drive them), **Python vs R** (COSG →
COSGR, cytome → cytome (R); everything else via a `.cytome` handoff), and **which annotation
route** (marker sets, reference projection, joint embedding, or a gene list against PIASOmarkerDB).

### Inside `piaso-tools`

Full reference: [`canonical/components/piaso.md`](canonical/components/piaso.md). Every function
takes `data=` as an AnnData, an open cytome Dataset or a `.cytome` path.

**Methods introduced by PIASO**

| Capability | Entry point | What it does |
|---|---|---|
| INFOG normalization | `piaso.tl.infog` | Information-content normalization of raw UMI counts + informative-gene selection |
| GDR (marker-gene-guided DR) | `piaso.tl.runGDR` / `runGDRParallel` / `projectGDR` | Embedding whose axes are per-group COSG-marker scores; integrates batches by identity; frozen reference spaces |
| Gene-set scoring (PIASOscore) | `piaso.tl.score` | Expression-matched-control scoring with per-cell p-values; whole pathway databases in one Rust matmul |
| Cell-type prediction | `piaso.tl.predictCellTypeByMarker` / `predictCellTypeByGDR` | Marker-set and reference-based annotation |
| SCALAR (single-cell LR) | `piaso.tl.specificity_matrix` + `runSCALAR` | Cell-type-resolved ligand–receptor inference for dissociated data, CellChatDB via `piaso.data.load_lr_database` |
| Marker-guided integration | `piaso.tl.stitchSpace` | Batch correction of an embedding via COSG-marker graph pruning |
| PIASOmarkerDB | `piaso.tl.getMarkers` / `analyzeMarkers` | Client for the curated marker database (36 studies, live API) |
| Motif scanning | `piaso.pp.scan_motifs` + `piaso.data` motif/genome loaders | The Rust PWM engine cytorete builds on |

**Pipeline building blocks (scanpy-free)**

| Capability | Entry point |
|---|---|
| Read 10x / Cell Ranger | `piaso.pp.read_10x_h5`, `read_10x`, `importCellRanger` (→ cytome) |
| QC, doublets, filtering | `piaso.pp.calculateCellMetrics`, `scrublet`, `filter_cells`, `calculateGroupMetrics` |
| Embedding, graph, clusters, UMAP | `piaso.tl.runSVD`, `neighbors`, `leiden`, `umap`, `leiden_local`, `runHarmony` |
| Datasets, genomes, motif DBs, CellChatDB | `piaso.data.load_dataset`, `fetch_genome`, `fetch_2bit`, `fetch_jaspar`, `load_lr_database` |
| Plotting | `piaso.pl.embedding`, `dotplot`, `violin`, `scatter`, `sankey`, `stackedBarplot`, `plot_embeddings_split` (+ tissue-image overlays on cytomes), `piaso.settings.set_figure_params` |

## What an agent gets

- `canonical/overview.md` — the router: task → component table and the seven decision rules.
- `canonical/components/` — self-sufficient references for PIASO, COSG (+ COSGR), cytome (+ R),
  LARIS, Emergene, cytorete, with executed code blocks and the data-object contract of every call.
- `canonical/workflows/` — end-to-end scRNA-seq (scanpy-free), streaming on a `.cytome`,
  marker-based annotation + reference projection, PIASOmarkerDB annotation, ligand–receptor
  (SCALAR and LARIS), spatial transcriptomics, gene regulatory networks.
- `canonical/gotchas.md` (layer contracts, deprecated names, the `as_dict` tuple, species-cased
  prefixes), `canonical/data.md` (registry, fixtures), and the **piaso.org tutorial index**
  (generated into every target) so the agent can point the user at the executed tutorial for
  their platform.

## Install (per agent)

Users work in **their own** analysis repos, so drop the right snippet into your setup. All of
these are generated from `canonical/` and live under [`dist/`](dist/).

**Claude Code** — add this repo as a plugin marketplace and install the `piaso` skill:
```bash
claude plugin marketplace add genecell/PIASO-for-agents
claude plugin install piaso@PIASO-for-agents
```

**Claude.ai (web app)** — upload the generated skill as a Skill (Pro/Max/Team/Enterprise, with
code execution enabled). Download the [`dist/claude/skills/piaso/`](dist/claude/skills/piaso)
folder, zip it, then in claude.ai go to **Settings → Capabilities → Skills → Create skill** and
upload the zip:
```bash
# from a clone of this repo:
cd dist/claude/skills && zip -r piaso-skill.zip piaso    # -> upload piaso-skill.zip in claude.ai
```
The local MCP server below is stdio-only, so it does **not** work in the web app — use the Skill
upload (or the `llms.txt` URL) on claude.ai; use MCP in Claude Code / Cursor / Codex.

**Cursor** — download the rule into your project's `.cursor/rules/`:
```bash
curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/cursor/.cursor/rules/piaso.mdc \
  -o .cursor/rules/piaso.mdc
```

**GitHub Copilot** — copy the instructions file into your repo:
```bash
curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/copilot/.github/copilot-instructions.md \
  -o .github/copilot-instructions.md
```

**OpenAI Codex** — add the `AGENTS.md` pointer below to your project's `AGENTS.md` (Codex's
primary instructions file), and/or register the MCP server (see the **MCP server** section
below — Codex is covered there).

**AGENTS.md (Aider / Zed / Codex / any AGENTS.md-aware agent)** — append the hub pointer to
your project's `AGENTS.md` (or copy [`dist/agents/AGENTS.md`](dist/agents/AGENTS.md)):
> This project uses the PIASO single-cell omics ecosystem. Agent-neutral, tested docs for
> every component (Python + R), plus the cross-component decision rules, live at
> https://github.com/genecell/PIASO-for-agents

**llms.txt (any model with web access)** — point the tool at:
```
https://piaso.org/llms.txt          # and https://piaso.org/llms-full.txt
```
These are the hub's `dist/llms/piaso.org/` files (absolute links); the relative-link versions are
at `dist/llms/`.

## MCP server

`piaso-mcp` serves the PIASO ecosystem docs, the **piaso.org tutorial index**, the **PIASO-data
registry** and the **live PIASOmarkerDB** — no Python packages required. Tools: `search_docs`,
`get_api`, `compare_implementations`, `resolve_install`, `list_tutorials`, `version_matrix`,
`check_versions` (PyPI vs tested versions), `list_datasets` / `get_dataset` (live registry), and
the live DB proxies `query_marker_db`, `get_markers`, `list_studies`. It is a **local stdio**
server (not a hosted remote endpoint), so it works in Claude Code / Cursor / VS Code / Windsurf /
Zed / Codex / Cline, but **not** in the claude.ai web app — use the Skill upload there.

### Prerequisite (all clients): `uv`

The server runs via `uvx`, which ships with **`uv`**. T