interpro-database

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: interpro-database
description: >
  Identify domains, families, and sites in proteins; find all proteins in a
  family or sharing a domain; explore species distribution for a domain;
  annotate genomes with protein families and GO terms. InterPro combines 14
  databases (e.g., Pfam, CDD) into one searchable resource. InterPro-N
  significantly expands annotation and sequence coverage with deep learning.
  Includes domain architecture (IDA) search.
---

# InterPro Database Access

## 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/interpro_database_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/interpro/ and
    https://www.ebi.ac.uk/about/terms-of-use/, then (2) create the file
    recording the notification text and timestamp.

## Overview

InterPro combines signatures from multiple, diverse databases into a single
searchable resource, reducing redundancy and helping users interpret their
sequence analysis results. By uniting these member databases (e.g., Pfam, CDD,
SMART), InterPro capitalises on their individual strengths to produce a powerful
diagnostic tool and integrated resource.

Use `interpro-database` to:

-   Identify what domains, families, and sites are found in a particular
    protein.
-   Identify all proteins that belong to a protein family or contain a
    particular domain, even when the names and activities of the proteins are
    highly variable.
-   Examine the species in which a particular protein family or domain is found.
-   Annotate genomes with protein family information and Gene Ontology (GO)
    terms.

This skill provides a robust utility, `interpro_client.py`, to interact with the
InterPro API seamlessly. It natively handles rate limiting (HTTP 429),
background query sleep tracking (HTTP 408), terminal errors (HTTP 404/410), and
lazy pagination.

## Core Rules

-   **Use the Wrapper**: ALWAYS execute the `scripts/interpro_client.py` helper
    script to query the database rather than accessing the database directly.
    The scripts automatically enforce fair use and implement retry logic.
-   **For exploratory queries**: ALWAYS use the CLI with a strict `--limit`.
    This allows you to rapidly understand the data schema without polluting your
    context window or fetching millions of results.
-   **Output to file**: Use the CLI with --output to output to a file rather
    than attempting to print it all to the console. Process the output using jq
    or code.
-   **For more complex pipelines** import the module natively into your Python
    scripts to consume the generator directly, preventing the need to
    deserialize CLI strings in large workflows.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

Examples:

```bash
uv run ./scripts/interpro_client.py fetch protein --source_db reviewed --limit 2 --query_params tax_id=9606 --output exploratory_results.jsonl
```

```python
import sys
sys.path.append('scripts')
from interpro_client import fetch_interpro_data
import itertools

# fetch_interpro_data lazily yields results page-by-page
results = fetch_interpro_data(
    endpoint="entry",
    source_db="pfam",
    query_params={"page_size": 10}
)
for match in itertools.islice(results, 10):
    print(match["metadata"]["accession"])
```

### 4 Ways to Construct Endpoints:

The arguments strictly map to the four common API path constructions. **Do not
format your own `/` separated strings:**

1.  **`/{endpoint}`** (e.g. `/entry`) `uv run ./scripts/interpro_client.py fetch
    entry --limit 10 --output entries.jsonl`
2.  **`/{endpoint}/{sourceDB}`** (e.g. `/entry/pfam`) `uv run
    ./scripts/interpro_client.py fetch entry --source_db pfam --limit 10
    --output pfam_entries.jsonl`
3.  **`/{endpoint}/{sourceDB}/{accession}`** (e