agr-curation-api-client 0.1.0__py3-none-any.whl

agr_curation_api/__init__.py

@@ -0,0 +1,39 @@
+"""AGR Curation API Client.
+
+A unified Python client for Alliance of Genome Resources (AGR) A-Team curation APIs.
+"""
+
+from .client import AGRCurationAPIClient
+from .exceptions import (
+    AGRAPIError,
+    AGRAuthenticationError,
+    AGRConnectionError,
+    AGRTimeoutError,
+    AGRValidationError,
+)
+from .models import (
+    APIConfig,
+    Gene,
+    Species,
+    OntologyTerm,
+    ExpressionAnnotation,
+    Allele,
+    APIResponse,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "AGRCurationAPIClient",
+    "AGRAPIError",
+    "AGRAuthenticationError",
+    "AGRConnectionError",
+    "AGRTimeoutError",
+    "AGRValidationError",
+    "APIConfig",
+    "Gene",
+    "Species",
+    "OntologyTerm",
+    "ExpressionAnnotation",
+    "Allele",
+    "APIResponse",
+]

agr_curation_api/client.py

@@ -0,0 +1,347 @@
+"""Main client for AGR Curation API."""
+
+import json
+import logging
+import urllib.request
+from typing import Optional, Dict, Any, List, Union, Type
+from types import TracebackType
+
+from pydantic import ValidationError
+from fastapi_okta.okta_utils import get_authentication_token, generate_headers
+
+from .models import (
+    APIConfig,
+    Gene,
+    Species,
+    OntologyTerm,
+    ExpressionAnnotation,
+    Allele,
+    APIResponse,
+)
+from .exceptions import (
+    AGRAPIError,
+    AGRAuthenticationError,
+    AGRValidationError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AGRCurationAPIClient:
+    """Client for interacting with AGR A-Team Curation API."""
+
+    def __init__(self, config: Union[APIConfig, Dict[str, Any], None] = None):
+        """Initialize the API client.
+
+        Args:
+            config: API configuration object, dictionary, or None for defaults
+        """
+        if config is None:
+            config = APIConfig()  # type: ignore[call-arg]
+        elif isinstance(config, dict):
+            config = APIConfig(**config)
+
+        self.config = config
+        self.base_url = str(self.config.base_url)
+
+        # Initialize authentication token if not provided
+        if not self.config.okta_token:
+            self.config.okta_token = get_authentication_token()
+
+    def _get_headers(self) -> Dict[str, str]:
+        """Get headers with authentication token."""
+        if self.config.okta_token:
+            headers = generate_headers(self.config.okta_token)
+            return dict(headers)  # Ensure we return Dict[str, str]
+        return {"Content-Type": "application/json", "Accept": "application/json"}
+
+    def __enter__(self) -> "AGRCurationAPIClient":
+        """Context manager entry."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType]
+    ) -> None:
+        """Context manager exit."""
+        pass
+
+    def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make a request to the A-Team API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint
+            data: Request data for POST requests
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            AGRAPIError: On API errors
+            AGRAuthenticationError: On authentication failures
+        """
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+        headers = self._get_headers()
+
+        try:
+            if method.upper() == "GET":
+                request = urllib.request.Request(url=url, headers=headers)
+            else:
+                request_data = json.dumps(data or {}).encode('utf-8')
+                request = urllib.request.Request(
+                    url=url,
+                    method=method.upper(),
+                    headers=headers,
+                    data=request_data
+                )
+
+            with urllib.request.urlopen(request) as response:
+                if response.getcode() == 200:
+                    logger.debug("Request successful")
+                    res = response.read().decode('utf-8')
+                    return dict(json.loads(res))  # Ensure we return Dict[str, Any]
+                else:
+                    raise AGRAPIError(f"Request failed with status: {response.getcode()}")
+
+        except urllib.error.HTTPError as e:
+            if e.code == 401:
+                raise AGRAuthenticationError("Authentication failed")
+            else:
+                raise AGRAPIError(f"HTTP error {e.code}: {e.reason}")
+        except Exception as e:
+            raise AGRAPIError(f"Request failed: {str(e)}")
+
+    # Gene endpoints
+    def get_genes(
+        self,
+        data_provider: Optional[str] = None,
+        limit: int = 5000,
+        page: int = 0
+    ) -> List[Gene]:
+        """Get genes from A-Team API.
+
+        Args:
+            data_provider: Filter by data provider abbreviation (e.g., 'WB', 'MGI')
+            limit: Number of results per page
+            page: Page number (0-based)
+
+        Returns:
+            List of Gene objects
+        """
+        req_data = {}
+        if data_provider:
+            req_data["dataProvider.abbreviation"] = data_provider
+
+        url = f"gene/find?limit={limit}&page={page}"
+        response_data = self._make_request("POST", url, req_data)
+
+        genes = []
+        if "results" in response_data:
+            for gene_data in response_data["results"]:
+                try:
+                    genes.append(Gene(**gene_data))
+                except ValidationError as e:
+                    logger.warning(f"Failed to parse gene data: {e}")
+
+        return genes
+
+    def get_gene(self, gene_id: str) -> Optional[Gene]:
+        """Get a specific gene by ID.
+
+        Args:
+            gene_id: Gene curie or primary external ID
+
+        Returns:
+            Gene object or None if not found
+        """
+        try:
+            response_data = self._make_request("GET", f"gene/{gene_id}")
+            return Gene(**response_data)
+        except AGRAPIError:
+            return None
+
+    # Species endpoints
+    def get_species(self, limit: int = 100, page: int = 0) -> List[Species]:
+        """Get species data from A-Team API.
+
+        Args:
+            limit: Number of results per page
+            page: Page number (0-based)
+
+        Returns:
+            List of Species objects
+        """
+        url = f"species/findForPublic?limit={limit}&page={page}&view=ForPublic"
+        response_data = self._make_request("POST", url, {})
+
+        species_list = []
+        if "results" in response_data:
+            for species_data in response_data["results"]:
+                try:
+                    species_list.append(Species(**species_data))
+                except ValidationError as e:
+                    logger.warning(f"Failed to parse species data: {e}")
+
+        return species_list
+
+    # Ontology endpoints
+    def get_ontology_root_nodes(self, node_type: str) -> List[OntologyTerm]:
+        """Get ontology root nodes.
+
+        Args:
+            node_type: Type of ontology node (e.g., 'goterm', 'doterm', 'anatomicalterm')
+
+        Returns:
+            List of OntologyTerm objects
+        """
+        response_data = self._make_request("GET", f"{node_type}/rootNodes")
+
+        terms = []
+        if "entities" in response_data:
+            for term_data in response_data["entities"]:
+                if not term_data.get("obsolete", False):
+                    try:
+                        terms.append(OntologyTerm(**term_data))
+                    except ValidationError as e:
+                        logger.warning(f"Failed to parse ontology term: {e}")
+
+        return terms
+
+    def get_ontology_node_children(self, node_curie: str, node_type: str) -> List[OntologyTerm]:
+        """Get children of an ontology node.
+
+        Args:
+            node_curie: CURIE of the parent node
+            node_type: Type of ontology node
+
+        Returns:
+            List of child OntologyTerm objects
+        """
+        response_data = self._make_request("GET", f"{node_type}/{node_curie}/children")
+
+        terms = []
+        if "entities" in response_data:
+            for term_data in response_data["entities"]:
+                if not term_data.get("obsolete", False):
+                    try:
+                        terms.append(OntologyTerm(**term_data))
+                    except ValidationError as e:
+                        logger.warning(f"Failed to parse ontology term: {e}")
+
+        return terms
+
+    # Expression annotation endpoints
+    def get_expression_annotations(
+        self,
+        data_provider: str,
+        limit: int = 5000,
+        page: int = 0
+    ) -> List[ExpressionAnnotation]:
+        """Get expression annotations from A-Team API.
+
+        Args:
+            data_provider: Data provider abbreviation
+            limit: Number of results per page
+            page: Page number (0-based)
+
+        Returns:
+            List of ExpressionAnnotation objects
+        """
+        req_data = {"expressionAnnotationSubject.dataProvider.abbreviation": data_provider}
+        url = f"gene-expression-annotation/findForPublic?limit={limit}&page={page}&view=ForPublic"
+
+        response_data = self._make_request("POST", url, req_data)
+
+        annotations = []
+        if "results" in response_data:
+            for annotation_data in response_data["results"]:
+                try:
+                    annotations.append(ExpressionAnnotation(**annotation_data))
+                except ValidationError as e:
+                    logger.warning(f"Failed to parse expression annotation: {e}")
+
+        return annotations
+
+    # Allele endpoints
+    def get_alleles(
+        self,
+        data_provider: Optional[str] = None,
+        limit: int = 5000,
+        page: int = 0
+    ) -> List[Allele]:
+        """Get alleles from A-Team API.
+
+        Args:
+            data_provider: Filter by data provider abbreviation
+            limit: Number of results per page
+            page: Page number (0-based)
+
+        Returns:
+            List of Allele objects
+        """
+        req_data = {}
+        if data_provider:
+            req_data["dataProvider.abbreviation"] = data_provider
+
+        url = f"allele/find?limit={limit}&page={page}"
+        response_data = self._make_request("POST", url, req_data)
+
+        alleles = []
+        if "results" in response_data:
+            for allele_data in response_data["results"]:
+                try:
+                    alleles.append(Allele(**allele_data))
+                except ValidationError as e:
+                    logger.warning(f"Failed to parse allele data: {e}")
+
+        return alleles
+
+    def get_allele(self, allele_id: str) -> Optional[Allele]:
+        """Get a specific allele by ID.
+
+        Args:
+            allele_id: Allele curie or primary external ID
+
+        Returns:
+            Allele object or None if not found
+        """
+        try:
+            response_data = self._make_request("GET", f"allele/{allele_id}")
+            return Allele(**response_data)
+        except AGRAPIError:
+            return None
+
+    # Search methods
+    def search_entities(
+        self,
+        entity_type: str,
+        search_filters: Dict[str, Any],
+        limit: int = 5000,
+        page: int = 0
+    ) -> APIResponse:
+        """Generic search method for any entity type.
+
+        Args:
+            entity_type: Type of entity to search (e.g., 'gene', 'allele', 'species')
+            search_filters: Dictionary of search filters
+            limit: Number of results per page
+            page: Page number (0-based)
+
+        Returns:
+            APIResponse with search results
+        """
+        url = f"{entity_type}/find?limit={limit}&page={page}"
+        response_data = self._make_request("POST", url, search_filters)
+
+        try:
+            return APIResponse(**response_data)
+        except ValidationError as e:
+            raise AGRValidationError(f"Invalid API response: {str(e)}")

agr_curation_api/exceptions.py

@@ -0,0 +1,43 @@
+"""Exception classes for AGR Curation API Client."""
+
+from typing import Optional, Dict, Any
+
+
+class AGRAPIError(Exception):
+    """Base exception for all AGR API errors."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None, response_data: Optional[Dict[str, Any]] = None):
+        """Initialize AGR API error.
+
+        Args:
+            message: Error message
+            status_code: HTTP status code if applicable
+            response_data: Response data from API if available
+        """
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_data = response_data
+
+
+class AGRAuthenticationError(AGRAPIError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class AGRConnectionError(AGRAPIError):
+    """Raised when connection to API fails."""
+
+    pass
+
+
+class AGRTimeoutError(AGRAPIError):
+    """Raised when API request times out."""
+
+    pass
+
+
+class AGRValidationError(AGRAPIError):
+    """Raised when request validation fails."""
+
+    pass

agr_curation_api/models.py

@@ -0,0 +1,132 @@
+"""Data models for AGR Curation API Client."""
+
+from typing import Optional, Dict, Any
+from pydantic import BaseModel, Field, HttpUrl, field_validator
+from datetime import timedelta
+
+
+class APIConfig(BaseModel):
+    """Configuration for AGR Curation API client."""
+
+    base_url: HttpUrl = Field(
+        default_factory=lambda: HttpUrl("https://curation.alliancegenome.org/api"),
+        description="Base URL for the A-Team Curation API"
+    )
+    okta_token: Optional[str] = Field(None, description="Okta bearer token for authentication")
+    timeout: timedelta = Field(
+        default=timedelta(seconds=30),
+        description="Request timeout"
+    )
+    max_retries: int = Field(3, ge=0, description="Maximum number of retry attempts")
+    retry_delay: timedelta = Field(
+        default=timedelta(seconds=1),
+        description="Delay between retry attempts"
+    )
+    verify_ssl: bool = Field(True, description="Whether to verify SSL certificates")
+    headers: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional headers to include in requests"
+    )
+
+    @field_validator('timeout', 'retry_delay')
+    def validate_timedelta(cls, v: timedelta) -> timedelta:
+        """Ensure timedelta is positive."""
+        if v.total_seconds() <= 0:
+            raise ValueError("Timeout and retry_delay must be positive")
+        return v
+
+    class Config:
+        """Pydantic config."""
+
+        json_encoders = {
+            timedelta: lambda v: v.total_seconds()
+        }
+
+
+class Gene(BaseModel):
+    """Gene model from A-Team curation API."""
+
+    curie: Optional[str] = Field(None, description="Compact URI")
+    primary_external_id: Optional[str] = Field(None, alias="primaryExternalId", description="Primary external ID")
+    gene_symbol: Optional[dict] = Field(None, alias="geneSymbol", description="Gene symbol object")
+    gene_full_name: Optional[dict] = Field(None, alias="geneFullName", description="Gene full name object")
+    gene_systematic_name: Optional[dict] = Field(None, alias="geneSystematicName", description="Gene systematic name")
+    gene_synonyms: Optional[list[dict]] = Field(None, alias="geneSynonyms", description="Gene synonyms")
+    data_provider: Optional[dict] = Field(None, alias="dataProvider", description="Data provider")
+    taxon: Optional[dict] = Field(None, description="Taxon information")
+    obsolete: bool = Field(False, description="Whether gene is obsolete")
+
+    class Config:
+        populate_by_name = True
+
+
+class Species(BaseModel):
+    """Species model from A-Team curation API."""
+
+    curie: Optional[str] = Field(None, description="Compact URI")
+    abbreviation: str = Field(..., description="Species abbreviation")
+    display_name: Optional[str] = Field(None, alias="displayName", description="Display name")
+    full_name: Optional[str] = Field(None, alias="fullName", description="Full scientific name")
+
+    class Config:
+        populate_by_name = True
+
+
+class OntologyTerm(BaseModel):
+    """Ontology term model from A-Team curation API."""
+
+    curie: str = Field(..., description="Compact URI")
+    name: Optional[str] = Field(None, description="Term name")
+    definition: Optional[str] = Field(None, description="Term definition")
+    synonyms: Optional[list[dict]] = Field(None, description="Term synonyms")
+    obsolete: bool = Field(False, description="Whether term is obsolete")
+    namespace: Optional[str] = Field(None, description="Ontology namespace")
+
+    class Config:
+        populate_by_name = True
+
+
+class ExpressionAnnotation(BaseModel):
+    """Expression annotation model from A-Team curation API."""
+
+    curie: Optional[str] = Field(None, description="Compact URI")
+    expression_annotation_subject: Optional[dict] = Field(
+        None,
+        alias="expressionAnnotationSubject",
+        description="Expression annotation subject"
+    )
+    expression_pattern: Optional[dict] = Field(
+        None,
+        alias="expressionPattern",
+        description="Expression pattern"
+    )
+
+    class Config:
+        populate_by_name = True
+
+
+class Allele(BaseModel):
+    """Allele model from A-Team curation API."""
+
+    curie: Optional[str] = Field(None, description="Compact URI")
+    primary_external_id: Optional[str] = Field(None, alias="primaryExternalId", description="Primary external ID")
+    allele_symbol: Optional[dict] = Field(None, alias="alleleSymbol", description="Allele symbol")
+    allele_full_name: Optional[dict] = Field(None, alias="alleleFullName", description="Allele full name")
+    allele_synonyms: Optional[list[dict]] = Field(None, alias="alleleSynonyms", description="Allele synonyms")
+    data_provider: Optional[dict] = Field(None, alias="dataProvider", description="Data provider")
+    taxon: Optional[dict] = Field(None, description="Taxon information")
+    obsolete: bool = Field(False, description="Whether allele is obsolete")
+
+    class Config:
+        populate_by_name = True
+
+
+class APIResponse(BaseModel):
+    """Standard A-Team API response wrapper."""
+
+    total_results: int = Field(..., alias="totalResults", description="Total number of results")
+    returned_records: int = Field(..., alias="returnedRecords", description="Number of records returned")
+    results: list[Any] = Field(..., description="Result data")
+
+    class Config:
+        populate_by_name = True

agr_curation_api_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: agr-curation-api-client
+Version: 0.1.0
+Summary: Unified Python client for Alliance of Genome Resources (AGR) curation APIs
+Author-email: Alliance of Genome Resources <valearna@caltech.edu>
+Maintainer-email: Alliance Blue Team <valearna@caltech.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/alliance-genome/agr_curation_api_client
+Project-URL: Bug Reports, https://github.com/alliance-genome/agr_curation_api_client/issues
+Project-URL: Source, https://github.com/alliance-genome/agr_curation_api_client
+Project-URL: Documentation, https://github.com/alliance-genome/agr_curation_api_client#readme
+Keywords: agr,alliance,genome,curation,api,client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: fastapi_okta>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-python-dateutil; extra == "dev"
+Dynamic: license-file
+
+# AGR Curation API Client
+
+A unified Python client for Alliance of Genome Resources (AGR) curation APIs.
+
+## Features
+
+- **Unified Interface**: Single client for all AGR curation API endpoints
+- **Type Safety**: Full type hints and Pydantic models for request/response validation
+- **Retry Logic**: Automatic retry with exponential backoff for transient failures
+- **Authentication**: Support for API key and Okta token authentication
+- **Async Support**: Built on httpx for both sync and async operations
+- **Comprehensive Error Handling**: Detailed exceptions for different error scenarios
+
+## Installation
+
+```bash
+pip install agr-curation-api-client
+```
+
+For development:
+```bash
+git clone https://github.com/alliance-genome/agr_curation_api_client.git
+cd agr_curation_api_client
+make install-dev
+```
+
+## Authentication
+
+The client supports automatic Okta token generation using the same environment variables as other AGR services:
+
+```bash
+export OKTA_DOMAIN="your-okta-domain"
+export OKTA_API_AUDIENCE="your-api-audience"
+export OKTA_CLIENT_ID="your-client-id"
+export OKTA_CLIENT_SECRET="your-client-secret"
+```
+
+With these environment variables set, the client will automatically obtain an authentication token when initialized.
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from agr_curation_api import AGRCurationAPIClient, APIConfig
+
+# Option 1: Automatic authentication (requires OKTA env vars)
+client = AGRCurationAPIClient()
+
+# Option 2: Manual token configuration
+config = APIConfig(
+    base_url="https://curation.alliancegenome.org/api",
+    okta_token="your-okta-token"  # Optional - will auto-retrieve if not provided
+)
+client = AGRCurationAPIClient(config)
+
+# Use the client
+with client:
+    # Get genes from WormBase
+    genes = client.get_genes(data_provider="WB", limit=10)
+    
+    for gene in genes:
+        symbol = gene.gene_symbol.get("displayText", "") if gene.gene_symbol else ""
+        print(f"{gene.curie}: {symbol}")
+```
+
+### Working with Genes
+
+```python
+from agr_curation_api import AGRCurationAPIClient, Gene
+
+# Use default configuration
+client = AGRCurationAPIClient()
+
+# Get genes from a specific data provider
+wb_genes = client.get_genes(data_provider="WB", limit=100)
+print(f"Found {len(wb_genes)} WormBase genes")
+
+# Get a specific gene by ID
+gene = client.get_gene("WB:WBGene00001234")
+if gene:
+    print(f"Gene: {gene.gene_symbol}")
+    print(f"Full name: {gene.gene_full_name}")
+    print(f"Species: {gene.taxon}")
+
+# Get all genes (paginated)
+all_genes = client.get_genes(limit=5000, page=0)
+```
+
+### Working with Species
+
+```python
+# Get all species
+species_list = client.get_species()
+
+for species in species_list:
+    print(f"{species.abbreviation}: {species.display_name}")
+
+# Find a specific species
+wb_species = [s for s in species_list if s.abbreviation == "WB"]
+if wb_species:
+    print(f"WormBase: {wb_species[0].full_name}")
+```
+
+### Working with Ontology Terms
+
+```python
+# Get GO term root nodes
+go_roots = client.get_ontology_root_nodes("goterm")
+print(f"Found {len(go_roots)} GO root terms")
+
+# Get children of a specific GO term
+children = client.get_ontology_node_children("GO:0008150", "goterm")  # biological_process
+for child in children:
+    print(f"{child.curie}: {child.name}")
+
+# Get disease ontology terms
+disease_roots = client.get_ontology_root_nodes("doterm")
+
+# Get anatomical terms
+anatomy_roots = client.get_ontology_root_nodes("anatomicalterm")
+```
+
+### Working with Expression Annotations
+
+```python
+# Get expression annotations for WormBase
+wb_expressions = client.get_expression_annotations(
+    data_provider="WB",
+    limit=100
+)
+
+for expr in wb_expressions:
+    if expr.expression_annotation_subject:
+        gene_id = expr.expression_annotation_subject.get("primaryExternalId")
+        gene_symbol = expr.expression_annotation_subject.get("geneSymbol", {}).get("displayText")
+        print(f"Gene: {gene_id} ({gene_symbol})")
+        
+    if expr.expression_pattern:
+        anatomy = expr.expression_pattern.get("whereExpressed", {}).get("anatomicalStructure", {}).get("curie")
+        print(f"  Expressed in: {anatomy}")
+```
+
+### Working with Alleles
+
+```python
+# Get alleles from a specific data provider
+wb_alleles = client.get_alleles(data_provider="WB", limit=50)
+
+for allele in wb_alleles:
+    symbol = allele.allele_symbol.get("displayText", "") if allele.allele_symbol else ""
+    print(f"{allele.curie}: {symbol}")
+
+# Get a specific allele
+allele = client.get_allele("WB:WBVar00001234")
+if allele:
+    print(f"Allele: {allele.allele_symbol}")
+    print(f"Full name: {allele.allele_full_name}")
+```
+
+### Generic Search
+
+```python
+# Generic entity search
+search_filters = {
+    "dataProvider.abbreviation": "WB",
+    "geneSymbol.displayText": "daf-16"
+}
+
+results = client.search_entities(
+    entity_type="gene",
+    search_filters=search_filters,
+    limit=10
+)
+
+print(f"Total results: {results.total_results}")
+print(f"Returned: {results.returned_records}")
+
+for gene_data in results.results:
+    print(f"Found gene: {gene_data}")
+```
+
+### Error Handling
+
+```python
+from agr_curation_api import (
+    AGRAPIError,
+    AGRAuthenticationError,
+    AGRConnectionError,
+    AGRTimeoutError,
+    AGRValidationError
+)
+
+try:
+    reference = client.get_reference("invalid-id")
+except AGRAuthenticationError:
+    print("Authentication failed - check your credentials")
+except AGRValidationError as e:
+    print(f"Invalid data: {e}")
+except AGRTimeoutError:
+    print("Request timed out - try again later")
+except AGRConnectionError:
+    print("Connection failed - check network")
+except AGRAPIError as e:
+    print(f"API error: {e}")
+    if e.status_code:
+        print(f"Status code: {e.status_code}")
+```
+
+## Configuration Options
+
+The `APIConfig` class supports the following options:
+
+- `base_url`: Base URL for the A-Team Curation API (default: "https://curation.alliancegenome.org/api")
+- `okta_token`: Okta bearer token for authentication (auto-retrieved if not provided)
+- `timeout`: Request timeout in seconds (default: 30)
+- `max_retries`: Maximum retry attempts (default: 3)
+- `retry_delay`: Initial delay between retries in seconds (default: 1)
+- `verify_ssl`: Whether to verify SSL certificates (default: True)
+- `headers`: Additional headers to include in requests
+
+### Environment Variables
+
+The client uses the following environment variables for configuration:
+
+- `ATEAM_API`: Override the default A-Team API URL (default: uses production curation API)
+- `OKTA_DOMAIN`: Your Okta domain (required for automatic authentication)
+- `OKTA_API_AUDIENCE`: Your API audience (required for automatic authentication)
+- `OKTA_CLIENT_ID`: Your Okta client ID (required for automatic authentication)
+- `OKTA_CLIENT_SECRET`: Your Okta client secret (required for automatic authentication)
+
+## Development
+
+### Running Tests
+
+```bash
+make test
+```
+
+### Code Quality
+
+```bash
+# Run linting
+make lint
+
+# Run type checking
+make type-check
+
+# Format code
+make format
+
+# Run all checks
+make check
+```
+
+### Building Documentation
+
+```bash
+cd docs
+make html
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/alliance-genome/agr_curation_api_client/issues)
+- **Documentation**: [API Documentation](https://alliancegenome.org/api-docs)
+- **Contact**: software@alliancegenome.org

agr_curation_api_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agr_curation_api/__init__.py,sha256=CuU6FLasKqfC44NSMJJMtXdw7WirOJQMZrnGOQKCiio,751
+agr_curation_api/client.py,sha256=q3zxvLT883ze81l0eTPDzf1oS0FU1RJHXh6ikJBVs0M,11123
+agr_curation_api/exceptions.py,sha256=uL8n1HedcKb6-expueINIqGOT94LudtUBWG0VlldMAM,1019
+agr_curation_api/models.py,sha256=385HApbQNnICxOSxdXOxQfYG9sHpuE6EnuRKp4pPnvc,5331
+agr_curation_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agr_curation_api_client-0.1.0.dist-info/licenses/LICENSE,sha256=8TExF0H0g2oKEU4iBjTwrHl2_-1SeyI0RbXlP9wpk3c,1084
+agr_curation_api_client-0.1.0.dist-info/METADATA,sha256=FLpdtk5_1LIciDwBY1MZOzqjJ_mA8pYrVy3IFGOX_vc,9533
+agr_curation_api_client-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agr_curation_api_client-0.1.0.dist-info/top_level.txt,sha256=tgbwvkzQIp6Tc8co8KZrlAWJ3nJIGcg3R9rlQz4ooPQ,17
+agr_curation_api_client-0.1.0.dist-info/RECORD,,

agr_curation_api_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agr_curation_api_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alliance of Genome Resources
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agr_curation_api_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agr_curation_api