embl-ebi-ols

Files (11)

• SKILL.md
• api_reference.md · references/
• citation.bib · references/
• get_individual.py · scripts/
• get_ontology.py · scripts/
• get_property.py · scripts/
• get_stats.py · scripts/
• get_term.py · scripts/
• ols_utils.py · scripts/
• search_ols.py · scripts/
• suggest_ols.py · scripts/

SKILL.md (first lines)

# EMBL-EBI Ontology Lookup Service (OLS)

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If .licenses/embl_ebi_ols_LICENSE.txt does not
    already exist in the workspace root directory then (1) prominently notify
    the user to check the terms at https://www.ebi.ac.uk/ols4/api-docs, then (2)
    create the file recording the notification text and timestamp.

## Core Rules

-   [!IMPORTANT] **Use the Utility Scripts**: You MUST ALWAYS use the provided
    utility script under `scripts/` for all API interactions, including checking
    status. NEVER use `curl` or custom Python requests to query API directly.

-   **Rate Limiting & Resilience**: You MUST respect EBI's Terms of Use with a
    maximum 5 requests per second. The provided utility scripts automatically
    enforce this.

-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

## When to Use — Quick Recipes

Use this skill whenever a user query matches one of these patterns:

-   **Definition** of a disease, phenotype, or term → `get_term.py --obo_id <ID>
    --summary`
-   **Subtypes** or **children** of a term → `get_term.py --obo_id <ID>
    --relations children`
-   **Parent** of a term → `get_term.py --obo_id <ID> --relations parents`
-   **Ancestors** / disease **categories** / **classified under** → `get_term.py
    --obo_id <ID> --relations ancestors`
-   **Root terms** of an ontology → `get_term.py --ontology <id> --roots`
-   **Hierarchical** parents (is-a + part-of) → `get_term.py --obo_id <ID>
    --relations hierarchicalParents`
-   **Structures part of** / hierarchical children → `get_term.py --obo_id <ID>
    --relations hierarchicalChildren`
-   **Compare** direct vs hierarchical parents → `get_term.py --obo_id <ID>
    --relations parents,hierarchicalParents`
-   Search for a term (e.g., "apoptosis" in GO) → `search_ols.py --query "..."
    --ontology <id>`
-   Find a **GO term** matching a function → `search_ols.py --query "..."
    --ontology go --exact`
-   Search in **MONDO**, **CHEBI**, **CL**, **UBERON** → `search_ols.py --query
    "..." --ontology <id> --defining`
-   **Paginate** search results / next page → `search_ols.py --query "..."
    --rows N --start <offset>`
-   Autocomplete a partial name → `suggest_ols.py --query "..."`
-   Ontology metadata (e.g., EFO info) → `get_ontology.py --id <id>`
-   OLS index statistics → `get_stats.py`

> **Multi-step queries** (e.g., "What is the parent of myocardial infarction?"):
> When the user names a term but you don't know its OBO ID, complete in
> **exactly 2 steps** — do NOT search across multiple ontologies:
>
> 1.  **Search** in the single most appropriate ontology: `search_ols.py --query
>     "myocardial infarction" --ontology doid --exact --rows 1 --output
>     /tmp/step1.json`
> 2.  **Get relations** using the OBO ID from step 1: `get_term.py --obo_id
>     DOID:5844 --relations parents --output /tmp/step2.json`
>
> **Ontology selection rule**: ALWAYS use `doid` for common human diseases
> (e.g., diabetes, cancer), `hp` for phenotypes, `go` for gene functions,
> `chebi` for chemicals, `uberon` for anatomy, `cl` for cell types. Use `mondo`
> ONLY when cross-species context is explicitly mentioned or needed.

## Utility Scripts

**1. Search Terms Across Ontologies**

Search for ontology terms by keyword and return clean JSON.

```bash
uv run scripts/search_ols.py --query "diabetes" \
  --rows 5 --output /tmp/ols_search_results.json 2>/dev/null
```

> **Important**: `--output` is required for all scripts. Results are always
> written to the specified file. For larger output, you can limit `--rows`
> (e.g., 5-10) or paginate using `--start`.

*Returned Fields:* JSON results include `iri`, `label`, `description`,
`ontology_name`, `ontology_prefix`, `obo_id`, `short_form`, `type`,
`is_defining_ontology`, and `exact_synonyms`.

*Pagination:* Output includes a `pagination` block with `start`, `rows`, and
`has_more` so you can decide whether to fetch more results.

*Options:*

-   `--query`: Search string (required). Searches labels, synonyms,
    descriptions, and identifiers.
-   `--ontology`: Filter by ontology ID (e.g., `go`, `doid`, `efo`, `hp`).
    **Recommended** when you know which ontology to search — avoids noise from
    250+ ontologies.
-   `--type`: Filter by entity type: `class`, `property`, `individual`, or
    `ontology`.
-   `--exact`: Flag for exact label match only. **Use this for entity
    resolution** when mapping a user's string to a specific ontology term ID.
-   `--defining`: Only return terms from their defining (authoritative)
    ontology. E.g., `GO:0005634` only from GO, not cross-referenced copies.
-   `--obsolete`: Flag to include obsolete terms in results.
-   `--local`: Only return terms in their defining ontology.
-   `--childrenOf`: Restrict to children of given term IRI(s), comma-separated.
-   `--allChildrenOf`: Restrict to all children including transitive relations
    (part of, develops from), comma-separated IRIs.
-   `--queryFields`: Comma-separated fields to search in (e.g.,
    `label,synonym,description`).
-   `--fieldList`: Comma-separated fields to return.
-   `--groupField`: Group results by unique IRI.
-   `--isLeaf`: Only return leaf terms (no children).
-   `--rows`: Number of results to return (default 10).
-   `--start`: Pagination offset (default 0).
-   `--output`: File path to save results (**required**).

**2. Autocomplete / Suggest**

From Marvellbrazil/my-agentic-skills, MIT.