genos-client 0.1.0__tar.gz

genos_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 qiupinghust
+
+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.

genos_client-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: genos-client
+Version: 0.1.0
+Summary: Genos API client for accessing genomic analysis services
+Author-email: qiuping1 <qiuping1@genomics.cn>, chenjunhong <chenjunhong@genomics.cn>, tianyongjing <tianyongjing@genomics.cn>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/BGI-HangzhouAI/Genos
+Project-URL: Documentation, https://genos-client.readthedocs.io/
+Project-URL: Source, https://github.com/BGI-HangzhouAI/Genos/tree/main/sdk
+Project-URL: Issues, https://github.com/BGI-HangzhouAI/Genos/issues
+Keywords: genomics,variant,prediction,api,client,visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Requires-Dist: pyfaidx
+Requires-Dist: pyBigWig
+Requires-Dist: torch
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == "viz"
+Requires-Dist: pandas; extra == "viz"
+Dynamic: license-file
+
+![Genos header image](docs/_static/geno.png)
+
+# Genos
+
+[**Get API key**](#get-api-key) |
+[**Quick start**](#quick-start) 
+
+**Genos** is a Python SDK for accessing genomic analysis models through the GeneOS platform. It provides a unified interface for variant pathogenicity prediction, DNA sequence embedding extraction, RNA-seq coverage track prediction, and genomic visualization.
+
+
+## Features
+
+- 🧬 **Variant Prediction**: Assess pathogenicity of genetic variants
+- 🔬 **Embedding Extraction**: Extract deep learning embeddings from DNA sequences
+- 🧪 **RNA-seq Coverage Track Prediction**: Predict RNA-seq coverage tracks from genomic coordinates
+- 📊 **Genomic Visualization**: Plot and analyze genomic tracks
+- 🚀 **Easy to Use**: Simple, intuitive API with comprehensive error handling
+- 🔐 **Robust Authentication**: Automatic token validation and payment checking
+- ⚠️ **Comprehensive Error Handling**: Specific exceptions for different error types
+
+
+
+## Get API Key
+
+To use Genos, you need an API key from the DCS Cloud.
+
+### Request Access
+1. Log in to the [DCS Clould](https://cloud.stomics.tech/#/login) and navigate to **Personal Center → API Key Management**.
+2. Click **“Create API Key”**.
+3. Read the **“API Usage Notice”** and confirm your agreement.
+4. The system will automatically generate your exclusive API Key — **copy and keep it safe**.
+> ⚠️ Please store your key securely and avoid any unauthorized disclosure.
+
+### Usage Policy
+* The API Key is **for personal use only** — sharing, transferring, or publishing is strictly prohibited.
+* If the key is **leaked, misused, or used for illegal purposes**, the platform reserves the right to **immediately disable it**.
+* You can **manually deactivate** your key in the control panel at any time.
+
+## Installation
+### Install from Source
+```bash
+git clone https://github.com/BGI-HangzhouAI/Genos.git
+cd sdk
+pip install -e .
+```
+
+### Install from Pypi
+```bash
+pip install genos
+```
+
+### Requirements
+
+- Python 3.8 or higher
+- pip package manager
+
+
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from genos import create_client
+
+# Create client (uses GENOS_API_TOKEN environment variable)
+client = create_client()
+
+# Or provide token explicitly
+client = create_client(token="your_api_token_here")
+```
+
+### 1. Variant Pathogenicity Prediction
+
+Predict whether a genetic variant is pathogenic or benign:
+
+```python
+# Predict variant pathogenicity
+result = client.variant_predict("hg19", "chr6", 51484075, "T", "G")['result']
+
+print(f"Variant: {result['variant']}")
+print(f"Prediction: {result['prediction']}")
+print(f"Pathogenic Score: {result['score_Pathogenic']:.4f}")
+print(f"Benign Score: {result['score_Benign']:.4f}")
+```
+
+### 2. DNA Sequence Embedding Extraction
+
+Extract deep learning embeddings from DNA sequences:
+
+```python
+# Extract embedding for a single sequence
+sequence = "ATCGATCGATCGATCGATCGATCGATCG"
+result = client.get_embedding(sequence, model_name="Genos-1.2B")['result']
+
+print(f"Sequence Length: {result['sequence_length']}")
+print(f"Embedding Dimension: {result['embedding_dim']}")
+print(f"Embedding Shape: {result['embedding_shape']}")
+
+# Access the embedding vector
+embedding_vector = result['embedding']  # List of floats
+```
+
+**Available Models:**
+- `Genos-1.2B`: 1.2 billion parameter model
+- `Genos-10B`: 10 billion parameter model
+
+**Pooling Methods:**
+- `mean`: Average pooling across sequence
+- `max`: Max pooling
+- `last`: Use last token embedding
+- `none`: Return all token embeddings
+
+### 3. RNA-seq Coverage Track Prediction
+
+Predict RNA-seq coverage tracks based on genomic coordinates:
+
+```python
+# Predict RNA-seq coverage track
+result = client.rna_coverage_track_pred(chrom="chr6", start_pos=51484075)['result']
+
+print(f"Predicted coverage track: {result}")
+```
+
+
+## Advanced Configuration
+
+### Custom Embedding Service
+
+GenosClient allows users to configure a **custom embedding API endpoint**.  
+This is useful if you want to deploy your own embedding service locally or within your organization.  
+
+**Note:** Now, the variant prediction and RNA-seq coverage track prediction models are **not open-source** and cannot be self-hosted. Only the embedding service can be customized.
+
+```python
+from genos import GenosClient
+
+# Initialize the client with a custom embedding endpoint
+client = GenosClient(
+    token="your_custom_token",  # Your token for authenticating with your own embedding service
+    api_map={
+        # Only the embedding service can be customized
+        "embedding": "https://custom-embed-api.example.com/predict"
+    }
+)
+
+# Calls to variant and RNA APIs will still use the official hosted services
+```
+
+### Timeout Configuration
+
+Adjust request timeout for long-running operations:
+
+```python
+# Set 60-second timeout
+client = create_client(token="your_token", timeout=60)
+```
+
+## Error Handling
+
+Genos provides comprehensive error handling with specific exception types for different scenarios. All API responses follow a consistent format.
+
+### Error Response Format
+
+All error responses from the Genos API follow this structure:
+
+```json
+{
+  "result": {},
+  "status": "<HTTP_STATUS_CODE>",
+  "messages": "<ERROR_MESSAGE>"
+}
+```
+
+### Common Error Codes
+
+| Status Code | Error Message | Description |
+|-------------|---------------|-------------|
+| 400 | Insufficient balance | Your account balance is insufficient for the requested operation |
+| 401 | Invalid API Key | The provided API key is invalid or expired |
+| 500 | Internal server error | An unexpected error occurred on the server side |
+
+## Examples
+
+Complete examples are available in the [`examples/`](examples/) directory:
+
+- [`predict_variant.py`](examples/predict_variant.py): Variant pathogenicity prediction
+- [`embedding_extract.py`](examples/embedding_extract.py): DNA Sequence Embedding Extraction
+- [`rna_generator.py`](examples/rna_generator.py): RNA-seq Coverage Track Prediction
+- [`error_handling_demo.py`](examples/error_handling_demo.py): Comprehensive error handling examples
+
+
+
+## Primary Paper（**Replace with real information**）
+
+xxx, xxx, *et al.*  
+*Genos: A Unified Foundation Model for Genomic Sequence Understanding and Variant Interpretation.（ju）*  
+_GigaScience_, 2025.  
+[https://doi.org/10.xxxx/genos.2025.12345](https://doi.org/10.xxxx/genos.2025.12345)
+
+
+## How to Cite （**Replace with real information**）
+
+If you use the SDK, please include the following citation in your work:
+
+```bibtex
+@article{he2025genos,
+  title   = {Genos: A Unified Foundation Model for Genomic Sequence Understanding and Variant Interpretation},
+  author  = {xxx},
+  journal = {GigaSience},
+  year    = {2025},
+  doi     = {10.xxxx/genos.2025.12345}
+}

genos_client-0.1.0/README.md

@@ -0,0 +1,213 @@
+![Genos header image](docs/_static/geno.png)
+
+# Genos
+
+[**Get API key**](#get-api-key) |
+[**Quick start**](#quick-start) 
+
+**Genos** is a Python SDK for accessing genomic analysis models through the GeneOS platform. It provides a unified interface for variant pathogenicity prediction, DNA sequence embedding extraction, RNA-seq coverage track prediction, and genomic visualization.
+
+
+## Features
+
+- 🧬 **Variant Prediction**: Assess pathogenicity of genetic variants
+- 🔬 **Embedding Extraction**: Extract deep learning embeddings from DNA sequences
+- 🧪 **RNA-seq Coverage Track Prediction**: Predict RNA-seq coverage tracks from genomic coordinates
+- 📊 **Genomic Visualization**: Plot and analyze genomic tracks
+- 🚀 **Easy to Use**: Simple, intuitive API with comprehensive error handling
+- 🔐 **Robust Authentication**: Automatic token validation and payment checking
+- ⚠️ **Comprehensive Error Handling**: Specific exceptions for different error types
+
+
+
+## Get API Key
+
+To use Genos, you need an API key from the DCS Cloud.
+
+### Request Access
+1. Log in to the [DCS Clould](https://cloud.stomics.tech/#/login) and navigate to **Personal Center → API Key Management**.
+2. Click **“Create API Key”**.
+3. Read the **“API Usage Notice”** and confirm your agreement.
+4. The system will automatically generate your exclusive API Key — **copy and keep it safe**.
+> ⚠️ Please store your key securely and avoid any unauthorized disclosure.
+
+### Usage Policy
+* The API Key is **for personal use only** — sharing, transferring, or publishing is strictly prohibited.
+* If the key is **leaked, misused, or used for illegal purposes**, the platform reserves the right to **immediately disable it**.
+* You can **manually deactivate** your key in the control panel at any time.
+
+## Installation
+### Install from Source
+```bash
+git clone https://github.com/BGI-HangzhouAI/Genos.git
+cd sdk
+pip install -e .
+```
+
+### Install from Pypi
+```bash
+pip install genos
+```
+
+### Requirements
+
+- Python 3.8 or higher
+- pip package manager
+
+
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from genos import create_client
+
+# Create client (uses GENOS_API_TOKEN environment variable)
+client = create_client()
+
+# Or provide token explicitly
+client = create_client(token="your_api_token_here")
+```
+
+### 1. Variant Pathogenicity Prediction
+
+Predict whether a genetic variant is pathogenic or benign:
+
+```python
+# Predict variant pathogenicity
+result = client.variant_predict("hg19", "chr6", 51484075, "T", "G")['result']
+
+print(f"Variant: {result['variant']}")
+print(f"Prediction: {result['prediction']}")
+print(f"Pathogenic Score: {result['score_Pathogenic']:.4f}")
+print(f"Benign Score: {result['score_Benign']:.4f}")
+```
+
+### 2. DNA Sequence Embedding Extraction
+
+Extract deep learning embeddings from DNA sequences:
+
+```python
+# Extract embedding for a single sequence
+sequence = "ATCGATCGATCGATCGATCGATCGATCG"
+result = client.get_embedding(sequence, model_name="Genos-1.2B")['result']
+
+print(f"Sequence Length: {result['sequence_length']}")
+print(f"Embedding Dimension: {result['embedding_dim']}")
+print(f"Embedding Shape: {result['embedding_shape']}")
+
+# Access the embedding vector
+embedding_vector = result['embedding']  # List of floats
+```
+
+**Available Models:**
+- `Genos-1.2B`: 1.2 billion parameter model
+- `Genos-10B`: 10 billion parameter model
+
+**Pooling Methods:**
+- `mean`: Average pooling across sequence
+- `max`: Max pooling
+- `last`: Use last token embedding
+- `none`: Return all token embeddings
+
+### 3. RNA-seq Coverage Track Prediction
+
+Predict RNA-seq coverage tracks based on genomic coordinates:
+
+```python
+# Predict RNA-seq coverage track
+result = client.rna_coverage_track_pred(chrom="chr6", start_pos=51484075)['result']
+
+print(f"Predicted coverage track: {result}")
+```
+
+
+## Advanced Configuration
+
+### Custom Embedding Service
+
+GenosClient allows users to configure a **custom embedding API endpoint**.  
+This is useful if you want to deploy your own embedding service locally or within your organization.  
+
+**Note:** Now, the variant prediction and RNA-seq coverage track prediction models are **not open-source** and cannot be self-hosted. Only the embedding service can be customized.
+
+```python
+from genos import GenosClient
+
+# Initialize the client with a custom embedding endpoint
+client = GenosClient(
+    token="your_custom_token",  # Your token for authenticating with your own embedding service
+    api_map={
+        # Only the embedding service can be customized
+        "embedding": "https://custom-embed-api.example.com/predict"
+    }
+)
+
+# Calls to variant and RNA APIs will still use the official hosted services
+```
+
+### Timeout Configuration
+
+Adjust request timeout for long-running operations:
+
+```python
+# Set 60-second timeout
+client = create_client(token="your_token", timeout=60)
+```
+
+## Error Handling
+
+Genos provides comprehensive error handling with specific exception types for different scenarios. All API responses follow a consistent format.
+
+### Error Response Format
+
+All error responses from the Genos API follow this structure:
+
+```json
+{
+  "result": {},
+  "status": "<HTTP_STATUS_CODE>",
+  "messages": "<ERROR_MESSAGE>"
+}
+```
+
+### Common Error Codes
+
+| Status Code | Error Message | Description |
+|-------------|---------------|-------------|
+| 400 | Insufficient balance | Your account balance is insufficient for the requested operation |
+| 401 | Invalid API Key | The provided API key is invalid or expired |
+| 500 | Internal server error | An unexpected error occurred on the server side |
+
+## Examples
+
+Complete examples are available in the [`examples/`](examples/) directory:
+
+- [`predict_variant.py`](examples/predict_variant.py): Variant pathogenicity prediction
+- [`embedding_extract.py`](examples/embedding_extract.py): DNA Sequence Embedding Extraction
+- [`rna_generator.py`](examples/rna_generator.py): RNA-seq Coverage Track Prediction
+- [`error_handling_demo.py`](examples/error_handling_demo.py): Comprehensive error handling examples
+
+
+
+## Primary Paper（**Replace with real information**）
+
+xxx, xxx, *et al.*  
+*Genos: A Unified Foundation Model for Genomic Sequence Understanding and Variant Interpretation.（ju）*  
+_GigaScience_, 2025.  
+[https://doi.org/10.xxxx/genos.2025.12345](https://doi.org/10.xxxx/genos.2025.12345)
+
+
+## How to Cite （**Replace with real information**）
+
+If you use the SDK, please include the following citation in your work:
+
+```bibtex
+@article{he2025genos,
+  title   = {Genos: A Unified Foundation Model for Genomic Sequence Understanding and Variant Interpretation},
+  author  = {xxx},
+  journal = {GigaSience},
+  year    = {2025},
+  doi     = {10.xxxx/genos.2025.12345}
+}

genos_client-0.1.0/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_client-0.1.0/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_client-0.1.0/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"]