@saibolla/ada 0.1.2

package/skills/uniprot-database/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: uniprot-database
+description: Direct REST API access to UniProt. Protein searches, FASTA retrieval, ID mapping, Swiss-Prot/TrEMBL. For Python workflows with multiple databases, prefer bioservices (unified interface to 40+ services). Use this for direct HTTP/REST work or UniProt-specific control.
+license: Unknown
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# UniProt Database
+
+## Overview
+
+UniProt is the world's leading comprehensive protein sequence and functional information resource. Search proteins by name, gene, or accession, retrieve sequences in FASTA format, perform ID mapping across databases, access Swiss-Prot/TrEMBL annotations via REST API for protein analysis.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Searching for protein entries by name, gene symbol, accession, or organism
+- Retrieving protein sequences in FASTA or other formats
+- Mapping identifiers between UniProt and external databases (Ensembl, RefSeq, PDB, etc.)
+- Accessing protein annotations including GO terms, domains, and functional descriptions
+- Batch retrieving multiple protein entries efficiently
+- Querying reviewed (Swiss-Prot) vs. unreviewed (TrEMBL) protein data
+- Streaming large protein datasets
+- Building custom queries with field-specific search syntax
+
+## Core Capabilities
+
+### 1. Searching for Proteins
+
+Search UniProt using natural language queries or structured search syntax.
+
+**Common search patterns:**
+```python
+# Search by protein name
+query = "insulin AND organism_name:\"Homo sapiens\""
+
+# Search by gene name
+query = "gene:BRCA1 AND reviewed:true"
+
+# Search by accession
+query = "accession:P12345"
+
+# Search by sequence length
+query = "length:[100 TO 500]"
+
+# Search by taxonomy
+query = "taxonomy_id:9606"  # Human proteins
+
+# Search by GO term
+query = "go:0005515"  # Protein binding
+```
+
+Use the API search endpoint: `https://rest.uniprot.org/uniprotkb/search?query={query}&format={format}`
+
+**Supported formats:** JSON, TSV, Excel, XML, FASTA, RDF, TXT
+
+### 2. Retrieving Individual Protein Entries
+
+Retrieve specific protein entries by accession number.
+
+**Accession number formats:**
+- Classic: P12345, Q1AAA9, O15530 (6 characters: letter + 5 alphanumeric)
+- Extended: A0A022YWF9 (10 characters for newer entries)
+
+**Retrieve endpoint:** `https://rest.uniprot.org/uniprotkb/{accession}.{format}`
+
+Example: `https://rest.uniprot.org/uniprotkb/P12345.fasta`
+
+### 3. Batch Retrieval and ID Mapping
+
+Map protein identifiers between different database systems and retrieve multiple entries efficiently.
+
+**ID Mapping workflow:**
+1. Submit mapping job to: `https://rest.uniprot.org/idmapping/run`
+2. Check job status: `https://rest.uniprot.org/idmapping/status/{jobId}`
+3. Retrieve results: `https://rest.uniprot.org/idmapping/results/{jobId}`
+
+**Supported databases for mapping:**
+- UniProtKB AC/ID
+- Gene names
+- Ensembl, RefSeq, EMBL
+- PDB, AlphaFoldDB
+- KEGG, GO terms
+- And many more (see `/references/id_mapping_databases.md`)
+
+**Limitations:**
+- Maximum 100,000 IDs per job
+- Results stored for 7 days
+
+### 4. Streaming Large Result Sets
+
+For large queries that exceed pagination limits, use the stream endpoint:
+
+`https://rest.uniprot.org/uniprotkb/stream?query={query}&format={format}`
+
+The stream endpoint returns all results without pagination, suitable for downloading complete datasets.
+
+### 5. Customizing Retrieved Fields
+
+Specify exactly which fields to retrieve for efficient data transfer.
+
+**Common fields:**
+- `accession` - UniProt accession number
+- `id` - Entry name
+- `gene_names` - Gene name(s)
+- `organism_name` - Organism
+- `protein_name` - Protein names
+- `sequence` - Amino acid sequence
+- `length` - Sequence length
+- `go_*` - Gene Ontology annotations
+- `cc_*` - Comment fields (function, interaction, etc.)
+- `ft_*` - Feature annotations (domains, sites, etc.)
+
+**Example:** `https://rest.uniprot.org/uniprotkb/search?query=insulin&fields=accession,gene_names,organism_name,length,sequence&format=tsv`
+
+See `/references/api_fields.md` for complete field list.
+
+## Python Implementation
+
+For programmatic access, use the provided helper script `scripts/uniprot_client.py` which implements:
+
+- `search_proteins(query, format)` - Search UniProt with any query
+- `get_protein(accession, format)` - Retrieve single protein entry
+- `map_ids(ids, from_db, to_db)` - Map between identifier types
+- `batch_retrieve(accessions, format)` - Retrieve multiple entries
+- `stream_results(query, format)` - Stream large result sets
+
+**Alternative Python packages:**
+- **Unipressed**: Modern, typed Python client for UniProt REST API
+- **bioservices**: Comprehensive bioinformatics web services client
+
+## Query Syntax Examples
+
+**Boolean operators:**
+```
+kinase AND organism_name:human
+(diabetes OR insulin) AND reviewed:true
+cancer NOT lung
+```
+
+**Field-specific searches:**
+```
+gene:BRCA1
+accession:P12345
+organism_id:9606
+taxonomy_name:"Homo sapiens"
+annotation:(type:signal)
+```
+
+**Range queries:**
+```
+length:[100 TO 500]
+mass:[50000 TO 100000]
+```
+
+**Wildcards:**
+```
+gene:BRCA*
+protein_name:kinase*
+```
+
+See `/references/query_syntax.md` for comprehensive syntax documentation.
+
+## Best Practices
+
+1. **Use reviewed entries when possible**: Filter with `reviewed:true` for Swiss-Prot (manually curated) entries
+2. **Specify format explicitly**: Choose the most appropriate format (FASTA for sequences, TSV for tabular data, JSON for programmatic parsing)
+3. **Use field selection**: Only request fields you need to reduce bandwidth and processing time
+4. **Handle pagination**: For large result sets, implement proper pagination or use the stream endpoint
+5. **Cache results**: Store frequently accessed data locally to minimize API calls
+6. **Rate limiting**: Be respectful of API resources; implement delays for large batch operations
+7. **Check data quality**: TrEMBL entries are computational predictions; Swiss-Prot entries are manually reviewed
+
+## Resources
+
+### scripts/
+`uniprot_client.py` - Python client with helper functions for common UniProt operations including search, retrieval, ID mapping, and streaming.
+
+### references/
+- `api_fields.md` - Complete list of available fields for customizing queries
+- `id_mapping_databases.md` - Supported databases for ID mapping operations
+- `query_syntax.md` - Comprehensive query syntax with advanced examples
+- `api_examples.md` - Code examples in multiple languages (Python, curl, R)
+
+## Additional Resources
+
+- **API Documentation**: https://www.uniprot.org/help/api
+- **Interactive API Explorer**: https://www.uniprot.org/api-documentation
+- **REST Tutorial**: https://www.uniprot.org/help/uniprot_rest_tutorial
+- **Query Syntax Help**: https://www.uniprot.org/help/query-fields
+- **SPARQL Endpoint**: https://sparql.uniprot.org/ (for advanced graph queries)
+

package/skills/uniprot-database/references/api_examples.md

@@ -0,0 +1,413 @@
+# UniProt API Examples
+
+Practical code examples for interacting with the UniProt REST API in multiple languages.
+
+## Python Examples
+
+### Example 1: Basic Search
+```python
+import requests
+
+# Search for human insulin proteins
+url = "https://rest.uniprot.org/uniprotkb/search"
+params = {
+    "query": "insulin AND organism_id:9606 AND reviewed:true",
+    "format": "json",
+    "size": 10
+}
+
+response = requests.get(url, params=params)
+data = response.json()
+
+for result in data['results']:
+    print(f"{result['primaryAccession']}: {result['proteinDescription']['recommendedName']['fullName']['value']}")
+```
+
+### Example 2: Retrieve Protein Sequence
+```python
+import requests
+
+# Get human insulin sequence in FASTA format
+accession = "P01308"
+url = f"https://rest.uniprot.org/uniprotkb/{accession}.fasta"
+
+response = requests.get(url)
+print(response.text)
+```
+
+### Example 3: Custom Fields
+```python
+import requests
+
+# Get specific fields only
+url = "https://rest.uniprot.org/uniprotkb/search"
+params = {
+    "query": "gene:BRCA1 AND reviewed:true",
+    "format": "tsv",
+    "fields": "accession,gene_names,organism_name,length,cc_function"
+}
+
+response = requests.get(url, params=params)
+print(response.text)
+```
+
+### Example 4: ID Mapping
+```python
+import requests
+import time
+
+def map_uniprot_ids(ids, from_db, to_db):
+    # Submit job
+    submit_url = "https://rest.uniprot.org/idmapping/run"
+    data = {
+        "from": from_db,
+        "to": to_db,
+        "ids": ",".join(ids)
+    }
+
+    response = requests.post(submit_url, data=data)
+    job_id = response.json()["jobId"]
+
+    # Poll for completion
+    status_url = f"https://rest.uniprot.org/idmapping/status/{job_id}"
+    while True:
+        response = requests.get(status_url)
+        status = response.json()
+        if "results" in status or "failedIds" in status:
+            break
+        time.sleep(3)
+
+    # Get results
+    results_url = f"https://rest.uniprot.org/idmapping/results/{job_id}"
+    response = requests.get(results_url)
+    return response.json()
+
+# Map UniProt IDs to PDB
+ids = ["P01308", "P04637"]
+mapping = map_uniprot_ids(ids, "UniProtKB_AC-ID", "PDB")
+print(mapping)
+```
+
+### Example 5: Stream Large Results
+```python
+import requests
+
+# Stream all reviewed human proteins
+url = "https://rest.uniprot.org/uniprotkb/stream"
+params = {
+    "query": "organism_id:9606 AND reviewed:true",
+    "format": "fasta"
+}
+
+response = requests.get(url, params=params, stream=True)
+
+# Process in chunks
+with open("human_proteins.fasta", "w") as f:
+    for chunk in response.iter_content(chunk_size=8192, decode_unicode=True):
+        if chunk:
+            f.write(chunk)
+```
+
+### Example 6: Pagination
+```python
+import requests
+
+def get_all_results(query, fields=None):
+    """Get all results with pagination"""
+    url = "https://rest.uniprot.org/uniprotkb/search"
+    all_results = []
+
+    params = {
+        "query": query,
+        "format": "json",
+        "size": 500  # Max size per page
+    }
+
+    if fields:
+        params["fields"] = ",".join(fields)
+
+    while True:
+        response = requests.get(url, params=params)
+        data = response.json()
+        all_results.extend(data['results'])
+
+        # Check for next page
+        if 'next' in data:
+            url = data['next']
+        else:
+            break
+
+    return all_results
+
+# Get all human kinases
+results = get_all_results(
+    "protein_name:kinase AND organism_id:9606 AND reviewed:true",
+    fields=["accession", "gene_names", "protein_name"]
+)
+print(f"Found {len(results)} proteins")
+```
+
+## cURL Examples
+
+### Example 1: Simple Search
+```bash
+# Search for insulin proteins
+curl "https://rest.uniprot.org/uniprotkb/search?query=insulin&format=json&size=5"
+```
+
+### Example 2: Get Protein Entry
+```bash
+# Get human insulin in FASTA format
+curl "https://rest.uniprot.org/uniprotkb/P01308.fasta"
+```
+
+### Example 3: Custom Fields
+```bash
+# Get specific fields in TSV format
+curl "https://rest.uniprot.org/uniprotkb/search?query=gene:BRCA1&format=tsv&fields=accession,gene_names,length"
+```
+
+### Example 4: ID Mapping - Submit Job
+```bash
+# Submit mapping job
+curl -X POST "https://rest.uniprot.org/idmapping/run" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "from=UniProtKB_AC-ID&to=PDB&ids=P01308,P04637"
+```
+
+### Example 5: ID Mapping - Get Results
+```bash
+# Get mapping results (replace JOB_ID)
+curl "https://rest.uniprot.org/idmapping/results/JOB_ID"
+```
+
+### Example 6: Download All Results
+```bash
+# Download all human reviewed proteins
+curl "https://rest.uniprot.org/uniprotkb/stream?query=organism_id:9606+AND+reviewed:true&format=fasta" \
+  -o human_proteins.fasta
+```
+
+## R Examples
+
+### Example 1: Basic Search
+```r
+library(httr)
+library(jsonlite)
+
+# Search for insulin proteins
+url <- "https://rest.uniprot.org/uniprotkb/search"
+query_params <- list(
+  query = "insulin AND organism_id:9606",
+  format = "json",
+  size = 10
+)
+
+response <- GET(url, query = query_params)
+data <- fromJSON(content(response, "text"))
+
+# Extract accessions and names
+proteins <- data$results[, c("primaryAccession", "proteinDescription")]
+print(proteins)
+```
+
+### Example 2: Get Sequences
+```r
+library(httr)
+
+# Get protein sequence
+accession <- "P01308"
+url <- paste0("https://rest.uniprot.org/uniprotkb/", accession, ".fasta")
+
+response <- GET(url)
+sequence <- content(response, "text")
+cat(sequence)
+```
+
+### Example 3: Download to Data Frame
+```r
+library(httr)
+library(readr)
+
+# Get data as TSV
+url <- "https://rest.uniprot.org/uniprotkb/search"
+query_params <- list(
+  query = "gene:BRCA1 AND reviewed:true",
+  format = "tsv",
+  fields = "accession,gene_names,organism_name,length"
+)
+
+response <- GET(url, query = query_params)
+data <- read_tsv(content(response, "text"))
+print(data)
+```
+
+## JavaScript Examples
+
+### Example 1: Fetch API
+```javascript
+// Search for proteins
+async function searchUniProt(query) {
+  const url = `https://rest.uniprot.org/uniprotkb/search?query=${encodeURIComponent(query)}&format=json&size=10`;
+
+  const response = await fetch(url);
+  const data = await response.json();
+
+  return data.results;
+}
+
+// Usage
+searchUniProt("insulin AND organism_id:9606")
+  .then(results => console.log(results));
+```
+
+### Example 2: Get Protein Entry
+```javascript
+async function getProtein(accession, format = "json") {
+  const url = `https://rest.uniprot.org/uniprotkb/${accession}.${format}`;
+
+  const response = await fetch(url);
+
+  if (format === "json") {
+    return await response.json();
+  } else {
+    return await response.text();
+  }
+}
+
+// Usage
+getProtein("P01308", "fasta")
+  .then(sequence => console.log(sequence));
+```
+
+### Example 3: ID Mapping
+```javascript
+async function mapIds(ids, fromDb, toDb) {
+  // Submit job
+  const submitUrl = "https://rest.uniprot.org/idmapping/run";
+  const formData = new URLSearchParams({
+    from: fromDb,
+    to: toDb,
+    ids: ids.join(",")
+  });
+
+  const submitResponse = await fetch(submitUrl, {
+    method: "POST",
+    body: formData
+  });
+  const { jobId } = await submitResponse.json();
+
+  // Poll for completion
+  const statusUrl = `https://rest.uniprot.org/idmapping/status/${jobId}`;
+  while (true) {
+    const statusResponse = await fetch(statusUrl);
+    const status = await statusResponse.json();
+
+    if ("results" in status || "failedIds" in status) {
+      break;
+    }
+
+    await new Promise(resolve => setTimeout(resolve, 3000));
+  }
+
+  // Get results
+  const resultsUrl = `https://rest.uniprot.org/idmapping/results/${jobId}`;
+  const resultsResponse = await fetch(resultsUrl);
+  return await resultsResponse.json();
+}
+
+// Usage
+mapIds(["P01308", "P04637"], "UniProtKB_AC-ID", "PDB")
+  .then(mapping => console.log(mapping));
+```
+
+## Advanced Examples
+
+### Example: Batch Processing with Rate Limiting
+```python
+import requests
+import time
+from typing import List, Dict
+
+class UniProtClient:
+    def __init__(self, rate_limit=1.0):
+        self.base_url = "https://rest.uniprot.org"
+        self.rate_limit = rate_limit
+        self.last_request = 0
+
+    def _rate_limit(self):
+        """Enforce rate limiting"""
+        elapsed = time.time() - self.last_request
+        if elapsed < self.rate_limit:
+            time.sleep(self.rate_limit - elapsed)
+        self.last_request = time.time()
+
+    def batch_get_proteins(self, accessions: List[str],
+                          batch_size: int = 100) -> List[Dict]:
+        """Get proteins in batches"""
+        results = []
+
+        for i in range(0, len(accessions), batch_size):
+            batch = accessions[i:i + batch_size]
+            query = " OR ".join([f"accession:{acc}" for acc in batch])
+
+            self._rate_limit()
+
+            response = requests.get(
+                f"{self.base_url}/uniprotkb/search",
+                params={
+                    "query": query,
+                    "format": "json",
+                    "size": batch_size
+                }
+            )
+
+            if response.ok:
+                data = response.json()
+                results.extend(data.get('results', []))
+            else:
+                print(f"Error in batch {i//batch_size}: {response.status_code}")
+
+        return results
+
+# Usage
+client = UniProtClient(rate_limit=0.5)
+accessions = ["P01308", "P04637", "P12345", "Q9Y6K9"]
+proteins = client.batch_get_proteins(accessions)
+```
+
+### Example: Download with Progress Bar
+```python
+import requests
+from tqdm import tqdm
+
+def download_with_progress(query, output_file, format="fasta"):
+    """Download results with progress bar"""
+    url = "https://rest.uniprot.org/uniprotkb/stream"
+    params = {
+        "query": query,
+        "format": format
+    }
+
+    response = requests.get(url, params=params, stream=True)
+    total_size = int(response.headers.get('content-length', 0))
+
+    with open(output_file, 'wb') as f, \
+         tqdm(total=total_size, unit='B', unit_scale=True) as pbar:
+        for chunk in response.iter_content(chunk_size=8192):
+            f.write(chunk)
+            pbar.update(len(chunk))
+
+# Usage
+download_with_progress(
+    "organism_id:9606 AND reviewed:true",
+    "human_proteome.fasta"
+)
+```
+
+## Resources
+
+- API Documentation: https://www.uniprot.org/help/api
+- Interactive API Explorer: https://www.uniprot.org/api-documentation
+- Python client (Unipressed): https://github.com/multimeric/Unipressed
+- Bioservices package: https://bioservices.readthedocs.io/