hugging-science

Files (8)

• SKILL.md
• flagship-resources.md · references/
• review.md · references/
• topics-and-slugs.md · references/
• using-datasets.md · references/
• using-models.md · references/
• using-spaces.md · references/
• fetch_catalog.py · scripts/

SKILL.md (first lines)

# Hugging Science

Hugging Science is a curated, LLM-friendly index of scientific datasets, models, blog posts, and interactive demos for ML researchers. Use it to find candidate resources, then verify their author documentation and scientific suitability; curation does not establish quality, openness, or executable compatibility.

There are two related surfaces, and you should use both:

- **The catalog at `huggingscience.co`** — a static, parseable index of resources across 17 scientific domains. It exposes `llms.txt` (compact), `llms-full.txt` (full content), and `topics/<slug>.md` (per-domain). These are markdown files designed to be fetched and read.
- **The `hugging-science` Hugging Face organization** — `huggingface.co/hugging-science` — community-submitted datasets, models, and a changing collection of Gradio, Docker and static Spaces. Not every listing exposes an inference API.

The catalog *points to* resources hosted on the broader Hugging Face Hub. For example, ESM2 supports Transformers, while Evo2 requires its native runtime and OpenGenome2 needs explicit file-format handling. The catalog provides discovery; use each resource through its verified loader or service.

## When to use this skill

Engage this skill when the user's task involves AI/ML applied to science. Common signals:

- Names a scientific domain (protein, genome, molecule, crystal, weather, climate, galaxy, EEG, microbiome, pathology, plasma, …)
- Asks "is there a dataset/model for X" where X is scientific
- Wants to fine-tune on scientific data, evaluate on scientific benchmarks, or reproduce a scientific ML paper
- Asks about specific known scientific models (Evo-2, ESM2, BoltzGen, Nucleotide Transformer, AlphaFold-derived, etc.)
- Needs an interactive demo for a scientific task (binder design, theorem proving, etc.)

If the task is generic ML (recommendation systems, chatbot RAG, vision on cats and dogs), this skill is **not** the right tool — defer to general HF Hub knowledge instead.

## Core workflow

Most invocations follow this five-step loop. Start with the relevant topic, then assess the underlying resource independently.

### 1. Identify the domain(s)

Map the user's task to one or more of the 17 topic slugs:

`astronomy` · `benchmark` · `biology` · `biotechnology` · `chemistry` · `climate` · `conservation` · `earth-science` · `ecology` · `energy` · `engineering` · `genomics` · `materials-science` · `mathematics` · `medicine` · `physics` · `scientific-reasoning`

Some tasks span multiple topics (e.g., drug discovery → `chemistry` + `biology` + `medicine`). Fetch each relevant topic.

### 2. Fetch the relevant catalog content

Use the bundled script for clean, structured access:

```bash
python scripts/fetch_catalog.py topic biology
python scripts/fetch_catalog.py topic materials-science --filter models
python scripts/fetch_catalog.py search "protein language model"
python scripts/fetch_catalog.py all     # full llms-full.txt
```

You can also fetch the raw markdown directly:

- `https://huggingscience.co/llms.txt` — compact index
- `https://huggingscience.co/llms-full.txt` — every entry, every domain
- `https://huggingscience.co/topics/<slug>.md` — one domain (slug is hyphenated, e.g. `materials-science.md`, `earth-science.md`, `scientific-reasoning.md`)

Each entry is a markdown block with `Type`, `Tags`, `HuggingFace` URL (or `Link` for blogs), and a one-line description. See `references/topics-and-slugs.md` for the entry schema and slug list.

### 3. Pick the right resource(s)

Read the descriptions and tags. Match to the user's task with judgment, not keyword overlap. Things to weigh:

- **Scale fit** — Evo-2 40B is overkill for a quick sequence classification on a laptop; ESM2 35M might be perfect.
- **License and access** — most are open, but check the underlying HF model card.
- **Modality alignment** — DNA vs. protein vs. SMILES vs. crystal structure; many "biology" models are not interchangeable.
- **Recency / supersession** — if both an older and newer entry cover the same task, prefer newer unless there's a reason not to.

Explain material tradeoffs between plausible candidates. Proceed with the best fit when task requirements resolve the choice; ask only if a missing preference would materially change the result.

For domain-specific go-to picks (the "if in doubt, start here" entries), see `references/flagship-resources.md`.

### 4. Use the resource

The mechanics depend on resource type. Read the matching reference file before writing code:

- **Datasets** → `references/using-datasets.md` — loading via `datasets`, streaming for huge corpora, common columns, splits
- **Models** → `references/using-models.md` — supported Transformers loaders, native scientific runtimes, verified Inference Provider mappings and memory limits
- **Spaces (interactive demos)** → `references/using-spaces.md` — `gradio_client` schema discovery and the source-verified BoltzGen contract, with its current runtime limitation

The reference files are short and focused. If you're already fluent in the relevant API, skim; if not, read fully before writing code. The patterns are different from generic HF usage in a few important places (e.g., `trust_remote_code` requirements, scientific-data dtype gotchas).

Before using a selected resource, record its exact Hub repository and immutable
commit, dataset configuration/split, license, and preprocessing/tokenizer
revision. [Dataset `revision`](https://huggingface.co/docs/datasets/loading)
can pin a commit; a moving branch name alone does not freeze the resource.
Resources from the same organization still need explicit vocabulary, input
modality, normalization, and split-compatibility checks.

### 5. Cite the methodology

When the catalog has a blog post matching the task (`Type: blog` or in the Blog Posts section of a topic file), include its URL when you explain your approach to the user. Check the blog authorship and primary paper; methodology posts can answer "why this design" questions that model cards usually skip. Treat them like citations — a one-line "see <link> for the methodology behind X" is plenty.

## Authentication: HF_TOKEN

Many catalog resources are gated (clinical data, large foundation models, private Spaces). Authenticate via the `HF_TOKEN` environment variable.

**Load `HF_TOKEN` from a `.env` file when available** — that's where the user keeps secrets. Use `python-dotenv` at the top of any script that hits the HF API:

```python
from dotenv import load_dotenv
load_dotenv()    # picks up HF_TOKEN from .env in cwd or any parent dir
```

If `.env` doesn't exist or doesn't define `HF_TOKEN`, fall back gracefully — many resources are public and work without it. Don't hard-code tokens, don't echo them, and don't suggest `huggingface-cli login` as the primary path; the user prefers `.env`.

The `.env` file should contain a line like:

```
HF_TOKEN=hf_...
```

If you're creating a new project, also add `.env` to `.gitignore` if it isn't already there.

## A few important things to remember

**The catalog is curated, not exhaustive.** If a user needs a specific resource and Hugging Science doesn't list it, that doesn't mean it doesn't exist on HF Hub. Search HF Hub directly as a fallback. But always *start* with the catalog when the domain matches — the curation is the value.

**The entries are pointers.** Don't try to "use Hugging Science" as if it were an API. There is no Hugging Science inference endpoint. Every actionable resource lives on HF Hub or as a HF Space, and you use it via the standard HF tooling.

**Verify the actual runtime.** Some Transformers architectures require reviewed, revision-pinned custom code; others such as Evo2 use a separate package. `trust_remote_code=True` does not turn arbitrary Hub artifacts into compatible models, and current Datasets no longer supports loading scripts. Execution and uploads must be within the user's authorized scope; catalog membership alone does not supply that authorization.

**Scientific datasets are often large and weirdly-shaped.** Genomics corpora can be billions of tokens; cosmology images can be hundreds of GB; materials datasets contain non-standard objects (crystal structures, graphs). Prefer bounded streaming where the format supports it; multipart compressed files need separate handling. Inspect schema before assuming columns.

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills