interpro-database

Files (5)

• SKILL.md
• api_reference.md · references/
• citation.bib · references/
• example_responses.tsv · references/
• interpro_client.py · scripts/

SKILL.md (first lines)

# 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.g. `/entry/pfam/PF00001`) `uv
    run ./scripts/interpro_client.py fetch entry --source_db pfam --accession
    PF00001 --limit 10 --output pf00001_entry.jsonl`
4.  **`/{endpoint}/{sourceDB}/{linked_endpoint}/{sourceDB}/{accession}`** (e.g.
    `/entry/interpro/protein/uniprot/P04637`) `uv run
    ./scripts/interpro_client.py fetch entry \ --source_db interpro \
    --linked_endpoint protein \ --linked_source_db uniprot \ --linked_accession
    P04637 \ --limit 10 --output p04637_entries.jsonl`

## Valid Source Databases (`--source_db`)

Each endpoint only accepts specific `source_db` values. Using an invalid value
returns a 404 error.

*   **`/entry`** (16 values): `interpro`, `pfam`, `cathgene3d`, `ssf`,
    `panther`, `cdd`, `profile`, `smart`, `ncbifam`, `prosite`, `prints`,
    `hamap`, `pirsf`, `sfld`, `antifam`.
*   **`/protein`** (3 values): `uniprot` (all), `reviewed` (SwissProt),
    `unreviewed` (TrEMBL).
*   **`/structure`** (1 value): `pdb`.
*   **`/taxonomy`** (1 value): `uniprot`.
*   **`/proteome`** (1 value): `uniprot`.
*   **`/set`** (2 values): `pfam`, `cdd`.

## Quick Reference / Core Endpoints & Parameters

**For a complete, exhaustive list of all query parameters, see the
[Full API Reference](references/api_reference.md).**

The API is fully open and supports 6 core endpoints. You can combine them using
the linked parameters described above. Below is a nested list of the specific
query parameters available for each endpoint:

*   **`/entry`** (Domain, family, active site, repeat, or homologous superfamily

From Marvellbrazil/my-agentic-skills, MIT.