genos-client 0.1.0__py3-none-any.whl

docs/conf.py

@@ -0,0 +1,106 @@
+# Configuration file for the Sphinx documentation builder
+
+import os
+import sys
+from datetime import datetime
+from sphinx.ext.autodoc import between
+
+# -- Path setup --------------------------------------------------------------
+# Add the project root to sys.path so Sphinx can find modules
+sys.path.insert(0, os.path.abspath('../..'))  # Assuming docs/ is inside genos/docs/
+
+# -- Project information -----------------------------------------------------
+project = 'Genos SDK'
+author = 'Genos Team'
+copyright = f'{datetime.now().year}, {author}'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    'sphinx.ext.autodoc',       # Automatically generate documentation from docstrings
+    'sphinx.ext.viewcode',      # Add links to highlighted source code
+    'sphinx.ext.napoleon',      # Support for Google/NumPy style docstrings
+    'sphinx.ext.todo',          # Support for TODO directives
+    'sphinx.ext.autosummary',   # Generate API summary automatically
+    'myst_parser',              # Support Markdown files
+    'nbsphinx',                 # Support Jupyter Notebooks
+]
+
+# Recognized source file suffixes
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+# Automatically generate summary tables
+autosummary_generate = True
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'private-members': False,
+    'special-members': '__init__',
+    'inherited-members': True,
+    'show-inheritance': True,
+}
+
+
+# Notebook execution settings
+nbsphinx_execute = 'never'     # Do not execute notebook cells
+nbsphinx_allow_errors = True   # Ignore execution errors
+
+# Avoid adding module names as prefixes to class names
+add_module_names = False
+
+# Autodoc default options
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'show-inheritance': True,
+}
+
+# Do not add "View page source" link at the top
+html_show_sourcelink = False
+
+# Source code view settings
+viewcode_follow_imported_members = False
+
+# Enable TODOs in the documentation
+todo_include_todos = True
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'collapse_navigation': False,
+    'navigation_depth': 4,
+    'style_nav_header_background': '#343131',
+}
+html_static_path = ['_static']
+
+# -- Autodoc settings --------------------------------------------------------
+autoclass_content = 'class'      # Show only the class docstring, not __init__
+autodoc_member_order = 'bysource'  # Display members in source code order
+
+# -- Suppress specific warnings ----------------------------------------------
+suppress_warnings = [
+    'toc.not_readable',
+]
+
+# -- Napoleon settings ------------------------------------------------------
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_use_ivar = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# -- Custom docstring processing --------------------------------------------
+# Remove unnecessary metadata lines like @File, @Author, @Date, @Desc
+def process_docstring(app, what, name, obj, options, lines):
+    filtered = [
+        line for line in lines
+        if not line.startswith(("@File", "@Author", "@Mail", "@Date", "@Desc"))
+    ]
+    lines[:] = filtered
+
+def setup(app):
+    app.connect("autodoc-process-docstring", process_docstring)

genos/__init__.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+from .client import GenosClient
+
+
+def create_client(token: str = None, timeout: int = 30) -> GenosClient:
+    """
+    Factory function to create a GenosClient instance.
+
+    Example:
+        >>> from genos import create_client
+        >>> client = create_client(token="your_token")
+        >>> result = client.variant_predict("hg19", "chr6", 51484075, "T", "G")
+
+    Args:
+        token (str, optional): API access token. Default: None.
+        base_url (str, optional): Base URL of the Genos service.
+            Defaults to environment variable GENOS_API_URL or "http://localhost:5000".
+        timeout (int, optional): Request timeout in seconds. Default: 30.
+
+    Returns:
+        GenosClient: A configured client instance ready to make API calls.
+    """
+    return GenosClient(token=token, timeout=timeout)
+
+
+__all__ = ["GenosClient", "create_client"]
+

genos/api/__init__.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# api/__init__.py
+
+"""
+Genos API subpackage.
+
+This package contains modules that wrap individual Genos API endpoints:
+- HealthAPI: /health endpoint
+- VariantPredictorAPI: /predict endpoint
+"""
+
+from .health import HealthAPI
+from .variant_predictor import VariantPredictorAPI
+from .embedding_extractor import EmbeddingExtractorAPI
+from .rna_seq_coverage_track_prediction import RNASeqCoverageTrackPredictionAPI
+
+
+__all__ = ["HealthAPI", "VariantPredictorAPI", "EmbeddingExtractorAPI", "RNASeqCoverageTrackPredictionAPI"]

genos/api/embedding_extractor.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+import requests
+import time
+import logging
+from typing import List, Union
+from .health import BaseAPI
+from ..exceptions import APIRequestError, ValidationError
+import torch
+
+# 设置日志
+logger = logging.getLogger(__name__)
+
+
+class EmbeddingExtractorAPI(BaseAPI):
+    """Wrapper class for the Embedding Extraction API endpoints.
+    
+    This class handles requests to the embedding extraction endpoints,
+    including single sequence and batch processing.
+    """
+    
+    def __init__(self, session: requests.Session, base_url: str, timeout: int = 30, config=None):
+        """
+        Initialize the EmbeddingExtractorAPI client.
+        
+        Args:
+            session (requests.Session): Reusable HTTP session for API requests.
+            base_url (str): Base URL of the Genos service.
+            timeout (int, optional): Request timeout in seconds. Default is 30.
+            config (GenosConfig, optional): Configuration object for endpoint management.
+        """
+        super().__init__(session, base_url, timeout)
+        self.config = config
+    
+    def extract(self, sequence: str, model_name: str = "Genos-1.2B",
+                pooling_method: str = "mean") -> Union[dict, List[dict]]:
+        """
+        Extracts a numerical embedding representation for a given nucleotide sequence.
+
+        Args:
+            sequence (str ): DNA sequence string .
+            model_name (str, optional): Model name to use. Default is "Genos-1.2B".
+                Options: "Genos-1.2B", "Genos-10B"
+            pooling_method (str, optional): Pooling method. Default is "mean".
+                Options: "mean", "max", "last", "none"
+
+        Returns:
+            dict:
+                - "token_count": number of tokens
+                - "embedding_shape": shape of embedding array
+                - "embedding_dim": dimension of embedding
+                - "embedding": embedding array (list)
+        
+        Raises:
+            ValueError: If sequence is not a valid string or list.
+            ValidationError: If parameters are invalid.
+            APIRequestError: If the API request fails.
+        
+        Examples:
+            >>> # Single sequence
+            >>> result = embedding_api.extract("ATCGATCGATCG")
+            >>> print(result['embedding_dim'])
+            4096
+        """
+        # 判断是单个序列还是批量
+        if isinstance(sequence, str):
+            # 单个序列
+            return self._extract_single(sequence, model_name, pooling_method)
+        else:
+            raise ValueError("sequence must be a string or list of strings")
+    
+    def _extract_single(self, sequence: str, model_name: str, pooling_method: str) -> dict:
+        """内部方法：提取单个序列"""
+        # Validate input
+        if len(sequence) == 0:
+            raise ValidationError("sequence cannot be empty")
+        
+        # Check sequence length limit (128K characters)
+        if len(sequence) > 128000:
+            raise ValidationError("sequence length cannot exceed 128,000 bases")
+        
+        # Prepare request
+        # 从配置获取端点路径
+        if self.config:
+            endpoint = self.config.get_endpoint("embedding.extract")
+        else:
+            endpoint = ""  # 默认值（向后兼容）
+        
+        url = f"{self.base_url}{endpoint}"
+        payload = {
+            "sequence": sequence,
+            "model_name": model_name,
+            "pooling_method": pooling_method
+        }
+        
+        # Start timing
+        start_time = time.time()
+        
+        # Use the base class method for request handling with token validation
+        data = self._make_request('POST', url, json=payload)
+        
+        # Calculate elapsed time
+        elapsed_time = time.time() - start_time
+        
+        # Check response status - new format has 'status' field
+        # if data.get("status") != 200:
+        #     error_msg = data.get("messages", "Unknown API error")
+        #     raise APIRequestError(f"API request failed: {error_msg}")
+        
+        embedding = torch.tensor(data["result"]["embedding"])
+        data["result"]["embedding"] = embedding
+        # Print elapsed time to screen
+        logger.info(f"⏱️  Embedding extraction completed in {elapsed_time:.4f}s "
+                   f"(sequence_length={data.get('sequence_length', 'N/A')})")
+        res = {}
+        for key in ("result", "status", "message"):
+            res[key] = data.get(key)
+        return res

genos/api/health.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+import requests
+from abc import ABC, abstractmethod
+from ..exceptions import APIRequestError, PaymentInsufficientError, AuthenticationError
+
+
+class BaseAPI(ABC):
+    """Base class for all Genos API endpoints with token validation and error handling.
+    
+    This class provides common functionality for all API endpoints, including:
+    - Token validation and authentication error handling
+    - Payment/credit insufficiency checking
+    - Standardized error response handling
+    - HTTP status code validation
+    
+    Only responses with status code 200 are considered successful and will proceed
+    to further analysis. All other status codes will raise appropriate exceptions
+    with the received error message.
+    """
+    
+    def __init__(self, session: requests.Session, base_url: str, timeout: int = 30):
+        """
+        Initialize the base API client.
+        
+        Args:
+            session (requests.Session): Reusable HTTP session for API requests.
+            base_url (str): Base URL of the Genos service.
+            timeout (int, optional): Request timeout in seconds. Default is 30.
+        """
+        self.session = session
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+    
+    def _validate_response(self, response: requests.Response) -> dict:
+        """
+        Validate API response and handle different status codes.
+        
+        This method ensures that only successful responses (status code 200)
+        proceed to further analysis. All other status codes will print the
+        error information and raise appropriate exceptions.
+        
+        Args:
+            response (requests.Response): The HTTP response to validate.
+            
+        Returns:
+            dict: JSON response data if status code is 200.
+            
+        Raises:
+            APIRequestError: For all non-200 status codes with server error message.
+        """
+        status_code = response.status_code
+        
+        if status_code == 200:
+            # Success - proceed with analysis
+            return response.json()
+        else:
+            # Error responses - print error info and raise exception
+            try:
+                error_data = response.json()
+                error_message = error_data.get('messages', error_data.get('message', f'HTTP {status_code} error'))
+            except:
+                error_message = f'HTTP {status_code} error'
+            
+            # Print error status and message before raising exception
+            print(f"❌ API Error - Status Code: {status_code}")
+            print(f"❌ Error Message: {error_message}")
+            raise APIRequestError(f"API request failed: {error_message}", status_code)
+    
+    def _make_request(self, method: str, url: str, **kwargs) -> dict:
+        """
+        Make an HTTP request with automatic response validation.
+        
+        Args:
+            method (str): HTTP method (GET, POST, etc.).
+            url (str): Full URL for the request.
+            **kwargs: Additional arguments passed to requests.
+            
+        Returns:
+            dict: JSON response data for successful requests (status code 200).
+            
+        Raises:
+            APIRequestError: For non-200 responses or network issues.
+        """
+        try:
+            response = getattr(self.session, method.lower())(url, timeout=self.timeout, **kwargs)
+            return self._validate_response(response)
+        except requests.RequestException as e:
+            raise APIRequestError(f"Network request failed: {e}")
+
+
+class HealthAPI(BaseAPI):
+    """Wrapper class for the Health Check API endpoint.
+
+    This class handles requests to the `/health` endpoint, allowing clients
+    to verify that the Genos service is running and responsive.
+    """
+
+    def __init__(self, session: requests.Session, base_url: str, timeout: int = 30):
+        """
+        Initialize the HealthAPI client.
+
+        Args:
+            session (requests.Session): Reusable HTTP session for API requests.
+            base_url (str): Base URL of the Genos service.
+            timeout (int, optional): Request timeout in seconds. Default is 30.
+        """
+        super().__init__(session, base_url, timeout)
+
+    def check(self) -> dict:
+        """
+        Perform a health check request.
+
+        Returns:
+            dict: JSON response from the health endpoint, typically containing:
+                - "status": "healthy" or "unhealthy"
+                - "message": optional status message
+
+        Raises:
+            APIRequestError: If the request fails or the server is unreachable.
+        """
+        url = f"{self.base_url}/health"
+        return self._make_request('GET', url)

genos/api/rna_seq_coverage_track_prediction.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+import json
+import requests
+import time
+import logging
+from .health import BaseAPI
+from ..exceptions import APIRequestError
+
+CHROMOSOMES = ['chr1', 'chr2', 'chr3', 'chr4', 'chr5', 'chr6', 'chr7', 'chr8', 'chr9', 'chr10', 'chr11', 'chr12',
+               'chr13', 'chr14', 'chr15', 'chr16', 'chr17', 'chr18', 'chr19', 'chr20', 'chr21', 'chr22']
+
+# 设置日志
+logger = logging.getLogger(__name__)
+# Dictionary mapping chromosome names to their lengths (GRCh38/hg38)
+CHROM_LENGTHS = {
+    'chr1': 248956422,
+    'chr2': 242193529,
+    'chr3': 198295559,
+    'chr4': 190214555,
+    'chr5': 181538259,
+    'chr6': 170805979,
+    'chr7': 159345973,
+    'chr8': 145138636,
+    'chr9': 138394717,
+    'chr10': 133797422,
+    'chr11': 135086622,
+    'chr12': 133275309,
+    'chr13': 114364328,
+    'chr14': 107043718,
+    'chr15': 101991189,
+    'chr16': 90338345,
+    'chr17': 83257441,
+    'chr18': 80373285,
+    'chr19': 58617616,
+    'chr20': 64444167,
+    'chr21': 46709983,
+    'chr22': 50818468,
+    'chrX': 156040895,
+    'chrY': 57227415,
+}
+
+
+def check_chromosome(chrom: str) -> bool:
+    """
+    Check if the chromosome is valid.
+    """
+    return chrom in CHROMOSOMES
+
+
+def get_start_position_range(chrom: str, gen_length: int = 32000):
+    """
+    Return the allowed range for start_pos for the given chromosome.
+    Allowed: 1 ~ (chrom_length - 32000), inclusive.
+
+    Raises:
+        ValueError: If the chromosome is not recognized.
+    """
+    if chrom not in CHROM_LENGTHS:
+        raise ValueError(f"Unknown chromosome: {chrom}")
+    chrom_length = CHROM_LENGTHS[chrom]
+    # Ensure the end is not less than 1
+    end_pos = max(1, chrom_length - gen_length)
+    return end_pos  # inclusive of end_pos
+
+
+def check_valid_parameters(chrom: str, start_pos: int, gen_length: int = 32000):
+    """
+    Check if the parameters are valid.
+    Args:
+        chrom (str): Chromosome name.
+        start_pos (int): Start position.
+        gen_length (int): Generation length.
+    Returns:
+        True if the parameters are valid, False otherwise.
+    """
+    # check chromosome
+    if not check_chromosome(chrom):
+        raise ValueError(f"Invalid chromosome: {chrom}. Allowed: {', '.join(CHROMOSOMES)}")
+    # check start position
+    if not isinstance(start_pos, int) or start_pos <= 0:
+        raise ValueError(f"Start position must be a positive integer, but got {start_pos}")
+    end_pos_max = get_start_position_range(chrom, gen_length)
+    if start_pos > end_pos_max:
+        raise ValueError(f"Start position must be less than {end_pos_max}, but got {start_pos}")
+    return True
+
+
+class RNASeqCoverageTrackPredictionAPI(BaseAPI):
+    """Client for the RNA-seq Coverage Track Prediction service in GeneOS.
+
+    This class provides access to RNA-seq Coverage Track Prediction
+    models, allowing users to predict the coverage track of an RNA-seq
+    experiment based on the genomic coordinates.
+
+    """
+
+    def __init__(self, session: requests.Session, base_url: str, timeout: int = 30):
+        """
+        Initialize the RNA-seq Coverage Track Prediction API module.
+
+        Args:
+            session (requests.Session): Shared HTTP session from GenosClient.
+            base_url (str): Endpoint URL for RNA-seq Coverage Track Prediction service.
+            timeout (int, optional): Request timeout (seconds). Default: 30.
+        """
+        super().__init__(session, base_url, timeout)
+
+    def predict(self, chrom: str, start_pos: int) -> dict:
+        """
+        Predict the coverage track of an RNA-seq experiment based on the genomic coordinates.
+
+        Args:
+            chrom (str): Chromosome name.
+            start_pos (int): Start position.
+
+        Returns:
+            dict: A JSON response from the RNA-seq Coverage Track Prediction model containing the predicted coverage track.
+
+        Raises:
+            ValueError: If the parameters are invalid.
+            APIRequestError: If the API request fails.
+        """
+        # check parameters
+        check_valid_parameters(chrom, start_pos)
+
+        payload = {"chrom": chrom, "start_pos": start_pos}
+
+        start_time = time.time()
+        # Use the base class method for request handling with token validation
+        data = self._make_request('POST', self.base_url, json=payload)
+        elapsed_time = time.time() - start_time
+        print(f"RNA-seq coverage track prediction completed in {elapsed_time:.4f}s")
+        res = {}
+        for key in ("result", "status", "message"):
+            res[key] = data.get(key)
+        return res
+
+

genos/api/variant_predictor.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import requests
+import time
+import logging
+from .health import BaseAPI
+from ..exceptions import APIRequestError
+
+logger = logging.getLogger(__name__)
+
+CHROMOSOMES = ['chr1', 'chr2', 'chr3', 'chr4', 'chr5', 'chr6', 'chr7', 'chr8', 'chr9', 'chr10', 'chr11', 'chr12', 'chr13', 'chr14', 'chr15', 'chr16', 'chr17', 'chr18', 'chr19', 'chr20', 'chr21', 'chr22', 'chrX', 'chrY']
+
+ALLOWED_RANGES = {
+    'hg38': {'chr1': (10001, 248946422), 'chr2': (10001, 242183529), 'chr3': (10001, 198235559), 'chr4': (10001, 190204555), 'chr5': (10001, 181478259), 'chr6': (60001, 170745979), 'chr7': (10001, 159335973), 'chr8': (60001, 145078636), 'chr9': (10001, 138334717), 'chr10': (10001, 133787422), 'chr11': (60001, 135076622), 'chr12': (10001, 133265309), 'chr13': (16000001, 114354328), 'chr14': (16000001, 106883718), 'chr15': (17000001, 101981189), 'chr16': (10001, 90228345), 'chr17': (60001, 83247441), 'chr18': (10001, 80263285), 'chr19': (60001, 58607616), 'chr20': (60001, 64334167), 'chr21': (5010001, 46699983), 'chr22': (10510001, 50808468), 'chrX': (10001, 156030895), 'chrY': (10001, 57217415)}, 
+    'hg19': {'chr1': (10001, 249240621), 'chr2': (10001, 243189373), 'chr3': (60001, 197962430), 'chr4': (10001, 191044276), 'chr5': (10001, 180905260), 'chr6': (60001, 171055067), 'chr7': (10001, 159128663), 'chr8': (10001, 146304022), 'chr9': (10001, 141153431), 'chr10': (60001, 135524747), 'chr11': (60001, 134946516), 'chr12': (60001, 133841895), 'chr13': (19020001, 115109878), 'chr14': (19000001, 107289540), 'chr15': (20000001, 102521392), 'chr16': (60001, 90294753), 'chr17': (1, 81195210), 'chr18': (10001, 78017248), 'chr19': (60001, 59118983), 'chr20': (60001, 62965520), 'chr21': (9411194, 48119895), 'chr22': (16050001, 51244566), 'chrX': (60001, 155260560), 'chrY': (10001, 59363566)}
+    }
+
+
+def check_chromosome(chrom: str) -> bool:
+    """
+    Check if the chromosome is valid.
+    """
+    return chrom in CHROMOSOMES
+
+
+def check_position(assembly: str, chrom: str, pos: int) -> bool:
+    """
+    Check if the position is valid.
+    """
+    return ALLOWED_RANGES[assembly][chrom][0] <= pos <= ALLOWED_RANGES[assembly][chrom][1]
+
+
+
+class VariantPredictorAPI(BaseAPI):
+    """Wrapper class for the Variant Prediction API endpoint.
+
+    This class handles requests to the `/predict` endpoint for variant
+    pathogenicity prediction. It validates input and raises structured
+    SDK exceptions on errors.
+    """
+
+    def __init__(self, session: requests.Session, base_url: str, timeout: int = 30):
+        """
+        Initialize the VariantPredictorAPI client.
+
+        Args:
+            session (requests.Session): Reusable HTTP session for API requests.
+            base_url (str): Base URL of the Genos service.
+            timeout (int, optional): Request timeout in seconds. Default is 30.
+        """
+        super().__init__(session, base_url, timeout)
+
+    def predict(self, assembly: str, chrom: str, pos: int, ref: str, alt: str) -> dict:
+        """
+        Predict the pathogenicity of a genetic variant.
+        
+        Args:
+            assembly (str): Reference genome version, allowed values: 'hg38' or 'hg19'.
+            chrom (str): Chromosome, e.g., 'chr6'.
+            pos (int): Position, 1-based coordinate.
+            ref (str): Reference allele, single letter or sequence.
+            alt (str): Alternate allele, single letter or sequence.
+
+        Returns:
+            dict: Prediction result, typically containing:
+                - "variant": input variant
+                - "prediction": "Pathogenic" or "Benign"
+                - "score_Benign": float
+                - "score_Pathogenic": float
+
+        Raises:
+            ValueError: If any argument is invalid.
+            APIRequestError: If the API request fails or the server returns an error.
+        """
+        # Validate assembly
+        allowed_assemblies = ["hg38", "hg19"]
+        if assembly not in allowed_assemblies:
+            raise ValueError(f"assembly must be one of {allowed_assemblies}, but got '{assembly}'")
+        
+        # Validate chromosome
+        if not check_chromosome(chrom):
+            raise ValueError(f"Invalid chromosome: {chrom}. Allowed: {', '.join(CHROMOSOMES)}")
+        
+        # Validate position
+        if not isinstance(pos, int) or not check_position(assembly, chrom, pos):
+            raise ValueError(f"Position {pos} not allowed on {assembly} {chrom}")
+        
+        # Validate reference and alternate alleles
+        valid_bases = set('ATCGN')
+        if not isinstance(ref, str) or len(ref) == 0 or any(base.upper() not in valid_bases for base in ref):
+            raise ValueError("ref allele must be a non-empty string composed only of nucleotides A, T, C, G, or N")
+        
+        if not isinstance(alt, str) or len(alt) == 0 or any(base.upper() not in valid_bases for base in alt):
+            raise ValueError("alt allele must be a non-empty string composed only of nucleotides A, T, C, G, or N")
+        
+        # Prepare payload with individual parameters
+        url = f"{self.base_url}"
+        payload = {
+            "assembly": assembly,
+            "chrom": chrom,
+            "pos": pos,
+            "ref": ref.upper(),
+            "alt": alt.upper()
+        }
+
+        start_time = time.time()
+
+        # Use the base class method for request handling with token validation
+        data = self._make_request('POST', url, json=payload)
+
+        elapsed_time = time.time() - start_time
+
+        # Check response status - new format has 'status' field
+        # if data.get("status") != 200:
+        #     error_msg = data.get("messages", "Unknown API error")
+        #     raise APIRequestError(f"API request failed: {error_msg}")
+
+        logger.info(f"Variant prediction completed in {elapsed_time:.4f}s ")
+
+        res = {}
+        for key in ("result", "status", "message"):
+            res[key] = data.get(key)
+        return res