biotailor 0.1.0__tar.gz

biotailor-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,93 @@
+# Copilot Instructions — biotailor (Python SDK)
+
+## Project Overview
+
+Python SDK for the [Biotailor](https://biotailor.com) bioinformatics pipeline platform. Provides programmatic access to create, run, and monitor bioinformatics pipelines via the Biotailor REST API.
+
+## Architecture
+
+```
+src/biotailor/
+├── __init__.py       # Public API exports (__all__) + __version__
+├── client.py         # BiotailorClient — main entry point, all HTTP methods
+├── models.py         # Dataclasses: ToolConfig, Job, Dataset, JobStatus, etc.
+├── pipeline.py       # Pipeline builder (fluent/chainable API)
+├── uploader.py       # S3 presigned URL uploads (single + multipart, concurrent)
+└── exceptions.py     # Exception hierarchy: BiotailorError → API/Validation/Upload
+```
+
+- **`client.py`** — `BiotailorClient` wraps all API calls (tools, jobs, datasets, uploads, downloads, polling). Uses `requests.Session` with Bearer auth.
+- **`models.py`** — Pure dataclasses mirroring backend JSON. Parsing helpers (`parse_tool_config`, `parse_job`, `parse_dataset`) convert camelCase API responses to snake_case fields.
+- **`pipeline.py`** — `Pipeline` is a chainable builder: `set_param()`, `set_input()`, `set_dataset()`, `set_hardware()`. Validates against `ToolConfig` and builds workflow JSON for the run endpoint.
+- **`uploader.py`** — Handles S3 uploads via presigned URLs. Supports single PUT and multipart uploads with retries, concurrent threads, and tqdm progress bars.
+- **`exceptions.py`** — Four exception classes: `BiotailorError` (base), `BiotailorAPIError` (HTTP errors with status_code), `BiotailorValidationError` (client-side), `BiotailorUploadError` (S3 failures).
+
+### Job Execution Flow
+
+```
+client.run(pipeline)
+  → POST /jobs           (create job)
+  → POST /jobs/{id}/run  (submit workflow, get upload URLs)
+  → PUT  presigned URLs  (upload files via uploader.py)
+  → POST /jobs/{id}/confirm-uploaded
+```
+
+`client.run_and_wait()` adds polling via `wait_for_completion()` + optional `download_outputs()`.
+
+## Dev Workflow
+
+```bash
+pip install -e ".[dev]"       # Install with dev deps (pytest, responses, ruff)
+pytest tests/ -v              # Run unit tests
+ruff check src/ tests/        # Lint
+```
+
+### Integration Tests
+
+Integration tests live in `tests/integration/` and hit a real API. They require `BIOTAILOR_API_KEY` env var and are not run in CI.
+
+## Conventions
+
+### Python Version & Style
+
+- **Target**: Python 3.9+ (`from __future__ import annotations` used throughout)
+- **Build system**: Hatchling
+- **Linter**: Ruff — line length 100, rules: E, F, I, N, W
+- **No type checker** configured (no mypy/pyright in dev deps)
+
+### Code Patterns
+
+- **Dataclasses** for all models — no Pydantic, no attrs
+- **`from __future__ import annotations`** at top of every module for PEP 604 style hints
+- **snake_case** for Python fields, **camelCase** for JSON keys sent to/from the API
+- **Parsing helpers** in `models.py` handle the camelCase→snake_case conversion (e.g. `displayName` → `display_name`)
+- **Fluent builder** pattern on `Pipeline` — all setter methods return `self`
+- **`requests`** library for HTTP — no `httpx`, no `aiohttp`
+- **`tqdm`** for progress bars (uploads + downloads)
+- **Logging** via `logging.getLogger("biotailor")` — debug mode controlled by `BiotailorClient(debug=True)`
+
+### Testing Patterns
+
+- **`responses`** library to mock HTTP calls (not `requests_mock`)
+- **`pytest-mock`** for general mocking
+- Shared fixtures and sample JSON payloads in `tests/conftest.py`
+- Test classes grouped by feature: `TestClientInit`, `TestListTools`, `TestRunPipeline`, etc.
+- API key for tests: `btk_abcdef123456.sk_0123456789abcdef0123456789abcdef` (from conftest)
+- Use `@responses.activate` decorator on test methods that mock HTTP
+
+### API Key Format
+
+Pattern: `btk_<hex>.sk_<hex>` — validated by regex in `BiotailorClient.__init__`.
+
+### Public API
+
+All public exports go in `__init__.py`'s `__all__` list. Keep this in sync when adding new models or classes.
+
+## Dependencies
+
+- **Runtime**: `requests>=2.28.0`, `tqdm>=4.64.0`
+- **Dev**: `pytest>=7.0`, `pytest-mock>=3.10`, `responses>=0.23`, `ruff>=0.1.0`
+
+## Relationship to Biotailor Backend
+
+This SDK talks to the same REST API served by the SST v2 backend in the `biotailor` monorepo. The workflow JSON schema, job statuses (`BUILDING`, `UPLOADING`, `STARTING`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`), and tool config shapes must stay in sync with `packages/core/` types in the backend.

biotailor-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Ruff
+.ruff_cache/
+
+.pypirc
+
+# Project-specific
+tests/integration/testdata/reads-large.fq

biotailor-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: biotailor
+Version: 0.1.0
+Summary: Python SDK for the Biotailor bioinformatics pipeline platform
+Author: Biotailor Team
+License-Expression: MIT
+Keywords: bioinformatics,biotailor,nextflow,pipeline
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Dist: requests>=2.28.0
+Requires-Dist: tqdm>=4.64.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.10; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# biotailor
+
+Python SDK for the [Biotailor](https://biotailor.com) bioinformatics pipeline platform.
+
+## Installation
+
+```bash
+pip install biotailor
+```
+
+## Quickstart
+
+```python
+from biotailor import BiotailorClient, Pipeline
+
+# 1. Create a client (get your API key from the Biotailor website)
+client = BiotailorClient(api_key="btk_xxx.sk_yyy")
+
+# 2. Discover available tools
+tools = client.list_tools()
+for t in tools:
+    print(f"{t.toolid}: {t.display_name}")
+
+# 3. Build a pipeline
+tool = client.get_tool("fastp-single")
+
+pipeline = (
+    Pipeline(name="QC my reads", tool=tool)
+    .set_input("input", "reads.fastq")
+    .set_param("qualified_quality_phred", 20)
+)
+
+# 4. Run and wait
+job = client.run_and_wait(pipeline, output_dir="./results")
+print(f"Job {job.jobid} finished with status: {job.job_status.value}")
+```
+
+## Development
+
+```bash
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Lint
+ruff check src/ tests/
+```

biotailor-0.1.0/README.md

@@ -0,0 +1,49 @@
+# biotailor
+
+Python SDK for the [Biotailor](https://biotailor.com) bioinformatics pipeline platform.
+
+## Installation
+
+```bash
+pip install biotailor
+```
+
+## Quickstart
+
+```python
+from biotailor import BiotailorClient, Pipeline
+
+# 1. Create a client (get your API key from the Biotailor website)
+client = BiotailorClient(api_key="btk_xxx.sk_yyy")
+
+# 2. Discover available tools
+tools = client.list_tools()
+for t in tools:
+    print(f"{t.toolid}: {t.display_name}")
+
+# 3. Build a pipeline
+tool = client.get_tool("fastp-single")
+
+pipeline = (
+    Pipeline(name="QC my reads", tool=tool)
+    .set_input("input", "reads.fastq")
+    .set_param("qualified_quality_phred", 20)
+)
+
+# 4. Run and wait
+job = client.run_and_wait(pipeline, output_dir="./results")
+print(f"Job {job.jobid} finished with status: {job.job_status.value}")
+```
+
+## Development
+
+```bash
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Lint
+ruff check src/ tests/
+```

biotailor-0.1.0/examples/reads.fastq

@@ -0,0 +1,36 @@
+@AS500713:64:HFKJJBGXY:1:11101:1675:1101 1:A:0:TATAGCCT+GACCCCCA
+
++
+
+@AS500713:64:HFKJJBGXY:1:11101:17113:1101 1:A:0:TATAGCCT+GTTTCTTA
+TACAAAATGCACATCGCTGAAAGGGGTAAAGGAGAGAAATCGCTTTATAAAACCTTGAAAAGGAATATTCAAATATAAGCTGGGAAGGTATAAAAAACTCTGTACATCACAAGTAAACAAATGGAACCTGCAAAATATTAAACAAAGGATT
++
+AAAAAEEEEE6EEAAAEEEEE6EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEAEEEEAEEEEEEEEEEEEEEEEECFE####EEEE6EE<AAEEEAEEEEEEEEEEEEAEEEEEEEA<E/AAEEEAEEEEE/EEEEAAEEE
+@AS500713:64:HFKJJBGXY:1:11101:1675:1101 1:A:0:TATAGCCT+GACCCCCA
+TAGGAGGCTTGGAGTACCAATAATAAAGTGAGCCCACCTTCCTGGTACCCAGACATTTCAGGAGGTCGGGAAATTTTTAAACCCAGGCAGCTTCCTGGCAGTGACATTTGGAGCATCAAAGTGGTAAATAAAATTTCATTTACATTAATAT
++
+6AAAAAEEEEE/E/EA/E/AEA6EE//AEE66/AAE//EEE/E//E/AA/EEE/A/AEE/EEA//EEEEEEEE6EEAAA/E###6E/6//6<EAAEEE/EEEA/EA/EEEEEE/<<EEEE//A/EE<AEEEEE/</AA</E<AAAE/E<E/
+@AS500713:64:HFKJJBGXY:1:11101:17113:1101 1:A:0:TATAGCCT+GTTTCTTA
+TACAAAATGCACATCGCTGAAAGGGGTAAAGGAGAGAAATCGCTTTATAAAACCTTGAAAAGGAATATTCAAATATAAGCTGGGAAGGTATAAAAAACTCTGTACATCACAAGTAAACAAATGGAACCTGCAAAATATTAAACAAAGGATT
++
+AAAAAEEEEE6EEAAAEEEEE6EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEAEEEEAEEEEEEEEEEEEEEEEEEEE/EEEEEEE6EE<AAEEEAEEEEEEEEEEEEAEEEEEEEA<E/AAEEEAEEEEE/EEEEAAEEE
+@AS500713:64:HFKJJBGXY:1:11101:1675:1101 1:A:0:TATAGCCT+GACCCCCA
+TAGGAGGCTTGGAGTACCAATAATAAAGTGAGCCCACCTTCCTGGTACCCAGACATTTCAGGAGGTCGGGAAATTTTTAAACCCAGGCAGCTTCCTGGCAGTGACATTTGGAGCATCAAAGTGGTAAATAAAATTTCATTTACATTAATAT
++
+6AAAAAEEEEE/E/EA/E/AEA6EE//AEE66/AAE//EEE/E//E/AA/EEE/A/AEE/EEA//EEEEEEEE6EEAAA/E/A/6E/6//6<EAAEEE/EEEA/EA/EEEEEE/<<EEEE//A/EE<AEEEEE/</AA</E<AAAE/E<E/
+@AS500713:64:HFKJJBGXY:1:11101:17113:1101 1:A:0:TATAGCCT+GTTTCTTA
+TACAAAATGCACATCGCTGAAAGGGGTAAAGGAGAGAAATCGCTTTATAAAACCTTGAAAAGGAATATTCAAATATAAGCTGGGAAGGTATAAAAAACTCTGTACATCACAAGTAAACAAATGGAACCTGCAAAATATTAAACAAAGGATT
++
+AAAAAEEEEE6EEAAAEEEEE6EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEAEEEEAEEEEEEEEEEEEEEEEEEEE/EEEEEEE6EE<AAEEEAEEEEEEEEEEEEAEEEEEEEA<E/AAEEEAEEEEE/EEEEAAEEE
+@AS500713:64:HFKJJBGXY:1:11101:1675:1101 1:A:0:TATAGCCT+GACCCCCA
+TAGGAGGCTTGGAGTACCAATAATAAAGTGAGCCCACCTTCCTGGTACCCAGACATTTCAGGAGGTCGGGAAATTTTTAAACCCAGGCAGCTTCCTGGCAGTGACATTTGGAGCATCAAAGTGGTAAATAAAATTTCATTTACATTAATAT
++
+6AAAAAEEEEE/E/EA/E/AEA6EE//AEE66/AAE//EEE/E//E/AA/EEE/A/AEE/EEA//EEEEEEEE6EEAAA/E/A/6E/6//6<EAAEEE/EEEA/EA/EEEEEE/<<EEEE//A/EE<AEEEEE/</AA</E<AAAE/E<E/
+@AS500713:64:HFKJJBGXY:1:11101:17113:1101 1:A:0:TATAGCCT+GTTTCTTA
+TACAAAATGCACATCGCTGAAAGGGGTAAAGGAGAGAAATCGCTTTATAAAACCTTGAAAAGGAATATTCAAATATAAGCTGGGAAGGTATAAAAAACTCTGTACATCACAAGTAAACAAATGGAACCTGCAAAATATTAAACAAAGGATT
++
+AAAAAEEEEE6EEAAAEEEEE6EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEAEEEEAEEEEEEEEEEEEEEEEEEEE/EEEEEEE6EE<AAEEEAEEEEEEEEEEEEAEEEEEEEA<E/AAEEEAEEEEE/EEEEAAEEE
+@AS500713:64:HFKJJBGXY:1:11101:17113:1101 1:A:0:TATAGCCT+GTTTCTTA
+CCCCCCCCCCACATCGCTGAAAGGGGTAAAGGAGAGAAATCGCTTTATAAAACCTTGAAAAGGAATATTCAAATATAAGCTGGGAAGGTATAAAAAACTCTGTACATCACAAGTAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
++
+AAAAAEEEEE6EEAAAEEEEE6EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEAEEEEAEEEEEEEEEEEEEEEEEEEE/EEEEEEE6EE<AAEEEAEEEEEEEEEEEEAEEEEEEEA<E/AAEEEAEEEEE/EEEEAAEEE

biotailor-0.1.0/examples/run_fastp.py

@@ -0,0 +1,26 @@
+"""Run a fastp quality-control pipeline in ~10 lines of code."""
+
+import os
+from biotailor import BiotailorClient, Pipeline
+
+# 1. Connect
+client = BiotailorClient(
+    api_key=os.environ["BIOTAILOR_API_KEY"],
+    base_url="https://api.dev-isaac.biotailor.org",
+)
+
+# 2. Pick a tool
+fastp = client.get_tool("fastp")
+
+# 3. Build the pipeline
+pipeline = (
+    Pipeline(name="demo-fastp", tool=fastp)
+    .set_pair_end(False)
+    .set_input("--in1", "examples/reads.fastq")
+    .set_param("--qualified_quality_phred", 20)
+    .set_param("--length_required", 30)
+)
+
+# 4. Run and wait
+job = client.run_and_wait(pipeline, output_dir="outputs/")
+print(f"Done! Status: {job.job_status.value}")

biotailor-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "biotailor"
+version = "0.1.0"
+description = "Python SDK for the Biotailor bioinformatics pipeline platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Biotailor Team" }]
+keywords = ["bioinformatics", "pipeline", "biotailor", "nextflow"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "tqdm>=4.64.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-mock>=3.10",
+    "responses>=0.23",
+    "ruff>=0.1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/biotailor"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

biotailor-0.1.0/src/biotailor/__init__.py

@@ -0,0 +1,41 @@
+"""Biotailor Python SDK — programmatic access to the Biotailor bioinformatics platform."""
+
+from biotailor.client import BiotailorClient
+from biotailor.exceptions import (
+    BiotailorAPIError,
+    BiotailorError,
+    BiotailorUploadError,
+    BiotailorValidationError,
+)
+from biotailor.models import (
+    Dataset,
+    DefaultHardware,
+    Job,
+    JobStatus,
+    Option,
+    Output,
+    ToolConfig,
+    ToolParameter,
+    Validation,
+)
+from biotailor.pipeline import Pipeline
+
+__all__ = [
+    "BiotailorClient",
+    "BiotailorAPIError",
+    "BiotailorError",
+    "BiotailorUploadError",
+    "BiotailorValidationError",
+    "Dataset",
+    "DefaultHardware",
+    "Job",
+    "JobStatus",
+    "Option",
+    "Output",
+    "Pipeline",
+    "ToolConfig",
+    "ToolParameter",
+    "Validation",
+]
+
+__version__ = "0.1.0"