@saibolla/ada 0.1.2

package/skills/openalex-database/scripts/query_helpers.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""
+Helper functions for common OpenAlex query patterns.
+
+Provides high-level functions for typical research queries.
+"""
+
+from typing import List, Dict, Optional, Any
+from openalex_client import OpenAlexClient
+
+
+def find_author_works(
+    author_name: str,
+    client: OpenAlexClient,
+    limit: Optional[int] = None
+) -> List[Dict[str, Any]]:
+    """
+    Find all works by an author (two-step pattern).
+
+    Args:
+        author_name: Author name to search for
+        client: OpenAlexClient instance
+        limit: Maximum number of works to return
+
+    Returns:
+        List of works by the author
+    """
+    # Step 1: Find author ID
+    author_response = client._make_request(
+        '/authors',
+        params={'search': author_name, 'per-page': 1}
+    )
+
+    if not author_response.get('results'):
+        print(f"No author found for: {author_name}")
+        return []
+
+    author = author_response['results'][0]
+    author_id = author['id'].split('/')[-1]  # Extract ID from URL
+
+    print(f"Found author: {author['display_name']} (ID: {author_id})")
+
+    # Step 2: Get works by author
+    works_params = {
+        'filter': f'authorships.author.id:{author_id}',
+        'per-page': 200
+    }
+
+    if limit and limit <= 200:
+        works_params['per-page'] = limit
+        response = client._make_request('/works', works_params)
+        return response.get('results', [])
+    else:
+        # Need pagination
+        return client.paginate_all('/works', works_params, max_results=limit)
+
+
+def find_institution_works(
+    institution_name: str,
+    client: OpenAlexClient,
+    limit: Optional[int] = None
+) -> List[Dict[str, Any]]:
+    """
+    Find all works from an institution (two-step pattern).
+
+    Args:
+        institution_name: Institution name to search for
+        client: OpenAlexClient instance
+        limit: Maximum number of works to return
+
+    Returns:
+        List of works from the institution
+    """
+    # Step 1: Find institution ID
+    inst_response = client._make_request(
+        '/institutions',
+        params={'search': institution_name, 'per-page': 1}
+    )
+
+    if not inst_response.get('results'):
+        print(f"No institution found for: {institution_name}")
+        return []
+
+    institution = inst_response['results'][0]
+    inst_id = institution['id'].split('/')[-1]  # Extract ID from URL
+
+    print(f"Found institution: {institution['display_name']} (ID: {inst_id})")
+
+    # Step 2: Get works from institution
+    works_params = {
+        'filter': f'authorships.institutions.id:{inst_id}',
+        'per-page': 200
+    }
+
+    if limit and limit <= 200:
+        works_params['per-page'] = limit
+        response = client._make_request('/works', works_params)
+        return response.get('results', [])
+    else:
+        return client.paginate_all('/works', works_params, max_results=limit)
+
+
+def find_highly_cited_recent_papers(
+    topic: Optional[str] = None,
+    years: str = ">2020",
+    client: Optional[OpenAlexClient] = None,
+    limit: int = 100
+) -> List[Dict[str, Any]]:
+    """
+    Find highly cited recent papers, optionally filtered by topic.
+
+    Args:
+        topic: Optional search term for topic filtering
+        years: Year filter (e.g., ">2020", "2020-2023")
+        client: OpenAlexClient instance
+        limit: Maximum number of papers to return
+
+    Returns:
+        List of highly cited papers sorted by citation count
+    """
+    if client is None:
+        client = OpenAlexClient()
+
+    params = {
+        'filter': f'publication_year:{years}',
+        'sort': 'cited_by_count:desc',
+        'per-page': min(limit, 200)
+    }
+
+    if topic:
+        params['search'] = topic
+
+    if limit <= 200:
+        response = client._make_request('/works', params)
+        return response.get('results', [])
+    else:
+        return client.paginate_all('/works', params, max_results=limit)
+
+
+def get_open_access_papers(
+    search_term: str,
+    client: OpenAlexClient,
+    oa_status: str = "any",  # "any", "gold", "green", "hybrid", "bronze"
+    limit: int = 100
+) -> List[Dict[str, Any]]:
+    """
+    Find open access papers on a topic.
+
+    Args:
+        search_term: Search query
+        client: OpenAlexClient instance
+        oa_status: Type of OA ("any" for is_oa:true, or specific status)
+        limit: Maximum number of papers to return
+
+    Returns:
+        List of open access papers
+    """
+    if oa_status == "any":
+        filter_str = "is_oa:true"
+    else:
+        filter_str = f"open_access.oa_status:{oa_status}"
+
+    params = {
+        'search': search_term,
+        'filter': filter_str,
+        'per-page': min(limit, 200)
+    }
+
+    if limit <= 200:
+        response = client._make_request('/works', params)
+        return response.get('results', [])
+    else:
+        return client.paginate_all('/works', params, max_results=limit)
+
+
+def get_publication_trends(
+    search_term: Optional[str] = None,
+    filter_params: Optional[Dict] = None,
+    client: Optional[OpenAlexClient] = None
+) -> List[Dict[str, Any]]:
+    """
+    Get publication counts by year.
+
+    Args:
+        search_term: Optional search query
+        filter_params: Optional additional filters
+        client: OpenAlexClient instance
+
+    Returns:
+        List of {year, count} dictionaries
+    """
+    if client is None:
+        client = OpenAlexClient()
+
+    params = {'group_by': 'publication_year'}
+
+    if search_term:
+        params['search'] = search_term
+
+    if filter_params:
+        filter_str = ','.join([f"{k}:{v}" for k, v in filter_params.items()])
+        params['filter'] = filter_str
+
+    response = client._make_request('/works', params)
+    return response.get('group_by', [])
+
+
+def analyze_research_output(
+    entity_type: str,  # 'author' or 'institution'
+    entity_name: str,
+    client: OpenAlexClient,
+    years: str = ">2020"
+) -> Dict[str, Any]:
+    """
+    Analyze research output for an author or institution.
+
+    Args:
+        entity_type: 'author' or 'institution'
+        entity_name: Name to search for
+        client: OpenAlexClient instance
+        years: Year filter
+
+    Returns:
+        Dictionary with analysis results
+    """
+    # Find entity ID
+    if entity_type == 'author':
+        endpoint = '/authors'
+        filter_prefix = 'authorships.author.id'
+    else:
+        endpoint = '/institutions'
+        filter_prefix = 'authorships.institutions.id'
+
+    # Step 1: Find entity
+    entity_response = client._make_request(
+        endpoint,
+        params={'search': entity_name, 'per-page': 1}
+    )
+
+    if not entity_response.get('results'):
+        return {'error': f'No {entity_type} found for: {entity_name}'}
+
+    entity = entity_response['results'][0]
+    entity_id = entity['id'].split('/')[-1]
+
+    # Step 2: Get statistics
+    filter_params = {
+        filter_prefix: entity_id,
+        'publication_year': years
+    }
+
+    # Total works
+    works_response = client.search_works(
+        filter_params=filter_params,
+        per_page=1
+    )
+    total_works = works_response['meta']['count']
+
+    # Works by year
+    trends = client.group_by(
+        'works',
+        'publication_year',
+        filter_params={filter_prefix: entity_id, 'publication_year': years}
+    )
+
+    # Top topics
+    topics = client.group_by(
+        'works',
+        'topics.id',
+        filter_params=filter_params
+    )
+
+    # OA percentage
+    oa_works = client.search_works(
+        filter_params={**filter_params, 'is_oa': 'true'},
+        per_page=1
+    )
+    oa_count = oa_works['meta']['count']
+    oa_percentage = (oa_count / total_works * 100) if total_works > 0 else 0
+
+    return {
+        'entity_name': entity['display_name'],
+        'entity_id': entity_id,
+        'total_works': total_works,
+        'open_access_works': oa_count,
+        'open_access_percentage': round(oa_percentage, 1),
+        'publications_by_year': trends[:10],  # Last 10 years
+        'top_topics': topics[:10]  # Top 10 topics
+    }
+
+
+if __name__ == "__main__":
+    # Example usage
+    import json
+
+    client = OpenAlexClient(email="your-email@example.com")
+
+    # Find works by author
+    print("\n=== Finding works by author ===")
+    works = find_author_works("Einstein", client, limit=5)
+    print(f"Found {len(works)} works")
+
+    # Analyze research output
+    print("\n=== Analyzing institution research output ===")
+    analysis = analyze_research_output('institution', 'MIT', client)
+    print(json.dumps(analysis, indent=2))

package/skills/opentargets-database/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: opentargets-database
+description: Query Open Targets Platform for target-disease associations, drug target discovery, tractability/safety data, genetics/omics evidence, known drugs, for therapeutic target identification.
+license: Unknown
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# Open Targets Database
+
+## Overview
+
+The Open Targets Platform is a comprehensive resource for systematic identification and prioritization of potential therapeutic drug targets. It integrates publicly available datasets including human genetics, omics, literature, and chemical data to build and score target-disease associations.
+
+**Key capabilities:**
+- Query target (gene) annotations including tractability, safety, expression
+- Search for disease-target associations with evidence scores
+- Retrieve evidence from multiple data types (genetics, pathways, literature, etc.)
+- Find known drugs for diseases and their mechanisms
+- Access drug information including clinical trial phases and adverse events
+- Evaluate target druggability and therapeutic potential
+
+**Data access:** The platform provides a GraphQL API, web interface, data downloads, and Google BigQuery access. This skill focuses on the GraphQL API for programmatic access.
+
+## When to Use This Skill
+
+This skill should be used when:
+
+- **Target discovery:** Finding potential therapeutic targets for a disease
+- **Target assessment:** Evaluating tractability, safety, and druggability of genes
+- **Evidence gathering:** Retrieving supporting evidence for target-disease associations
+- **Drug repurposing:** Identifying existing drugs that could be repurposed for new indications
+- **Competitive intelligence:** Understanding clinical precedence and drug development landscape
+- **Target prioritization:** Ranking targets based on genetic evidence and other data types
+- **Mechanism research:** Investigating biological pathways and gene functions
+- **Biomarker discovery:** Finding genes differentially expressed in disease
+- **Safety assessment:** Identifying potential toxicity concerns for drug targets
+
+## Core Workflow
+
+### 1. Search for Entities
+
+Start by finding the identifiers for targets, diseases, or drugs of interest.
+
+**For targets (genes):**
+```python
+from scripts.query_opentargets import search_entities
+
+# Search by gene symbol or name
+results = search_entities("BRCA1", entity_types=["target"])
+# Returns: [{"id": "ENSG00000012048", "name": "BRCA1", ...}]
+```
+
+**For diseases:**
+```python
+# Search by disease name
+results = search_entities("alzheimer", entity_types=["disease"])
+# Returns: [{"id": "EFO_0000249", "name": "Alzheimer disease", ...}]
+```
+
+**For drugs:**
+```python
+# Search by drug name
+results = search_entities("aspirin", entity_types=["drug"])
+# Returns: [{"id": "CHEMBL25", "name": "ASPIRIN", ...}]
+```
+
+**Identifiers used:**
+- Targets: Ensembl gene IDs (e.g., `ENSG00000157764`)
+- Diseases: EFO (Experimental Factor Ontology) IDs (e.g., `EFO_0000249`)
+- Drugs: ChEMBL IDs (e.g., `CHEMBL25`)
+
+### 2. Query Target Information
+
+Retrieve comprehensive target annotations to assess druggability and biology.
+
+```python
+from scripts.query_opentargets import get_target_info
+
+target_info = get_target_info("ENSG00000157764", include_diseases=True)
+
+# Access key fields:
+# - approvedSymbol: HGNC gene symbol
+# - approvedName: Full gene name
+# - tractability: Druggability assessments across modalities
+# - safetyLiabilities: Known safety concerns
+# - geneticConstraint: Constraint scores from gnomAD
+# - associatedDiseases: Top disease associations with scores
+```
+
+**Key annotations to review:**
+- **Tractability:** Small molecule, antibody, PROTAC druggability predictions
+- **Safety:** Known toxicity concerns from multiple databases
+- **Genetic constraint:** pLI and LOEUF scores indicating essentiality
+- **Disease associations:** Diseases linked to the target with evidence scores
+
+Refer to `references/target_annotations.md` for detailed information about all target features.
+
+### 3. Query Disease Information
+
+Get disease details and associated targets/drugs.
+
+```python
+from scripts.query_opentargets import get_disease_info
+
+disease_info = get_disease_info("EFO_0000249", include_targets=True)
+
+# Access fields:
+# - name: Disease name
+# - description: Disease description
+# - therapeuticAreas: High-level disease categories
+# - associatedTargets: Top targets with association scores
+```
+
+### 4. Retrieve Target-Disease Evidence
+
+Get detailed evidence supporting a target-disease association.
+
+```python
+from scripts.query_opentargets import get_target_disease_evidence
+
+# Get all evidence
+evidence = get_target_disease_evidence(
+    ensembl_id="ENSG00000157764",
+    efo_id="EFO_0000249"
+)
+
+# Filter by evidence type
+genetic_evidence = get_target_disease_evidence(
+    ensembl_id="ENSG00000157764",
+    efo_id="EFO_0000249",
+    data_types=["genetic_association"]
+)
+
+# Each evidence record contains:
+# - datasourceId: Specific data source (e.g., "gwas_catalog", "chembl")
+# - datatypeId: Evidence category (e.g., "genetic_association", "known_drug")
+# - score: Evidence strength (0-1)
+# - studyId: Original study identifier
+# - literature: Associated publications
+```
+
+**Major evidence types:**
+1. **genetic_association:** GWAS, rare variants, ClinVar, gene burden
+2. **somatic_mutation:** Cancer Gene Census, IntOGen, cancer biomarkers
+3. **known_drug:** Clinical precedence from approved/clinical drugs
+4. **affected_pathway:** CRISPR screens, pathway analyses, gene signatures
+5. **rna_expression:** Differential expression from Expression Atlas
+6. **animal_model:** Mouse phenotypes from IMPC
+7. **literature:** Text-mining from Europe PMC
+
+Refer to `references/evidence_types.md` for detailed descriptions of all evidence types and interpretation guidelines.
+
+### 5. Find Known Drugs
+
+Identify drugs used for a disease and their targets.
+
+```python
+from scripts.query_opentargets import get_known_drugs_for_disease
+
+drugs = get_known_drugs_for_disease("EFO_0000249")
+
+# drugs contains:
+# - uniqueDrugs: Total number of unique drugs
+# - uniqueTargets: Total number of unique targets
+# - rows: List of drug-target-indication records with:
+#   - drug: {name, drugType, maximumClinicalTrialPhase}
+#   - targets: Genes targeted by the drug
+#   - phase: Clinical trial phase for this indication
+#   - status: Trial status (active, completed, etc.)
+#   - mechanismOfAction: How drug works
+```
+
+**Clinical phases:**
+- Phase 4: Approved drug
+- Phase 3: Late-stage clinical trials
+- Phase 2: Mid-stage trials
+- Phase 1: Early safety trials
+
+### 6. Get Drug Information
+
+Retrieve detailed drug information including mechanisms and indications.
+
+```python
+from scripts.query_opentargets import get_drug_info
+
+drug_info = get_drug_info("CHEMBL25")
+
+# Access:
+# - name, synonyms: Drug identifiers
+# - drugType: Small molecule, antibody, etc.
+# - maximumClinicalTrialPhase: Development stage
+# - mechanismsOfAction: Target and action type
+# - indications: Diseases with trial phases
+# - withdrawnNotice: If withdrawn, reasons and countries
+```
+
+### 7. Get All Associations for a Target
+
+Find all diseases associated with a target, optionally filtering by score.
+
+```python
+from scripts.query_opentargets import get_target_associations
+
+# Get associations with score >= 0.5
+associations = get_target_associations(
+    ensembl_id="ENSG00000157764",
+    min_score=0.5
+)
+
+# Each association contains:
+# - disease: {id, name}
+# - score: Overall association score (0-1)
+# - datatypeScores: Breakdown by evidence type
+```
+
+**Association scores:**
+- Range: 0-1 (higher = stronger evidence)
+- Aggregate evidence across all data types using harmonic sum
+- NOT confidence scores but relative ranking metrics
+- Under-studied diseases may have lower scores despite good evidence
+
+## GraphQL API Details
+
+**For custom queries beyond the provided helper functions**, use the GraphQL API directly or modify `scripts/query_opentargets.py`.
+
+Key information:
+- **Endpoint:** `https://api.platform.opentargets.org/api/v4/graphql`
+- **Interactive browser:** `https://api.platform.opentargets.org/api/v4/graphql/browser`
+- **No authentication required**
+- **Request only needed fields** to minimize response size
+- **Use pagination** for large result sets: `page: {size: N, index: M}`
+
+Refer to `references/api_reference.md` for:
+- Complete endpoint documentation
+- Example queries for all entity types
+- Error handling patterns
+- Best practices for API usage
+
+## Best Practices
+
+### Target Prioritization Strategy
+
+When prioritizing drug targets:
+
+1. **Start with genetic evidence:** Human genetics (GWAS, rare variants) provides strongest disease relevance
+2. **Check tractability:** Prefer targets with clinical or discovery precedence
+3. **Assess safety:** Review safety liabilities, expression patterns, and genetic constraint
+4. **Evaluate clinical precedence:** Known drugs indicate druggability and therapeutic window
+5. **Consider multiple evidence types:** Convergent evidence from different sources increases confidence
+6. **Validate mechanistically:** Pathway evidence and biological plausibility
+7. **Review literature manually:** For critical decisions, examine primary publications
+
+### Evidence Interpretation
+
+**Strong evidence indicators:**
+- Multiple independent evidence sources
+- High genetic association scores (especially GWAS with L2G > 0.5)
+- Clinical precedence from approved drugs
+- ClinVar pathogenic variants with disease match
+- Mouse models with relevant phenotypes
+
+**Caution flags:**
+- Single evidence source only
+- Text-mining as sole evidence (requires manual validation)
+- Conflicting evidence across sources
+- High essentiality + ubiquitous expression (poor therapeutic window)
+- Multiple safety liabilities
+
+**Score interpretation:**
+- Scores rank relative strength, not absolute confidence
+- Under-studied diseases have lower scores despite potentially valid targets
+- Weight expert-curated sources higher than computational predictions
+- Check evidence breakdown, not just overall score
+
+### Common Workflows
+
+**Workflow 1: Target Discovery for a Disease**
+1. Search for disease → get EFO ID
+2. Query disease info with `include_targets=True`
+3. Review top targets sorted by association score
+4. For promising targets, get detailed target info
+5. Examine evidence types supporting each association
+6. Assess tractability and safety for prioritized targets
+
+**Workflow 2: Target Validation**
+1. Search for target → get Ensembl ID
+2. Get comprehensive target info
+3. Check tractability (especially clinical precedence)
+4. Review safety liabilities and genetic constraint
+5. Examine disease associations to understand biology
+6. Look for chemical probes or tool compounds
+7. Check known drugs targeting gene for mechanism insights
+
+**Workflow 3: Drug Repurposing**
+1. Search for disease → get EFO ID
+2. Get known drugs for disease
+3. For each drug, get detailed drug info
+4. Examine mechanisms of action and targets
+5. Look for related disease indications
+6. Assess clinical trial phases and status
+7. Identify repurposing opportunities based on mechanism
+
+**Workflow 4: Competitive Intelligence**
+1. Search for target of interest
+2. Get associated diseases with evidence
+3. For each disease, get known drugs
+4. Review clinical phases and development status
+5. Identify competitors and their mechanisms
+6. Assess clinical precedence and market landscape
+
+## Resources
+
+### Scripts
+
+**scripts/query_opentargets.py**
+Helper functions for common API operations:
+- `search_entities()` - Search for targets, diseases, or drugs
+- `get_target_info()` - Retrieve target annotations
+- `get_disease_info()` - Retrieve disease information
+- `get_target_disease_evidence()` - Get supporting evidence
+- `get_known_drugs_for_disease()` - Find drugs for a disease
+- `get_drug_info()` - Retrieve drug details
+- `get_target_associations()` - Get all associations for a target
+- `execute_query()` - Execute custom GraphQL queries
+
+### References
+
+**references/api_reference.md**
+Complete GraphQL API documentation including:
+- Endpoint details and authentication
+- Available query types (target, disease, drug, search)
+- Example queries for all common operations
+- Error handling and best practices
+- Data licensing and citation requirements
+
+**references/evidence_types.md**
+Comprehensive guide to evidence types and data sources:
+- Detailed descriptions of all 7 major evidence types
+- Scoring methodologies for each source
+- Evidence interpretation guidelines
+- Strengths and limitations of each evidence type
+- Quality assessment recommendations
+
+**references/target_annotations.md**
+Complete target annotation reference:
+- 12 major annotation categories explained
+- Tractability assessment details
+- Safety liability sources
+- Expression, essentiality, and constraint data
+- Interpretation guidelines for target prioritization
+- Red flags and green flags for target assessment
+
+## Data Updates and Versioning
+
+The Open Targets Platform is updated **quarterly** with new data releases. The current release (as of October 2025) is available at the API endpoint.
+
+**Release information:** Check https://platform-docs.opentargets.org/release-notes for the latest updates.
+
+**Citation:** When using Open Targets data, cite:
+Ochoa, D. et al. (2025) Open Targets Platform: facilitating therapeutic hypotheses building in drug discovery. Nucleic Acids Research, 53(D1):D1467-D1477.
+
+## Limitations and Considerations
+
+1. **API is for exploratory queries:** For systematic analyses of many targets/diseases, use data downloads or BigQuery
+2. **Scores are relative, not absolute:** Association scores rank evidence strength but don't predict clinical success
+3. **Under-studied diseases score lower:** Novel or rare diseases may have strong evidence but lower aggregate scores
+4. **Evidence quality varies:** Weight expert-curated sources higher than computational predictions
+5. **Requires biological interpretation:** Scores and evidence must be interpreted in biological and clinical context
+6. **No authentication required:** All data is freely accessible, but cite appropriately
+