bioartifact 0.1.0__tar.gz

bioartifact-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+*.bam binary
+*.gz binary
+

bioartifact-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: python -m unittest discover -s tests

bioartifact-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Check distributions
+        run: twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/bioartifact/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bioartifact-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+.DS_Store
+design.md
+DESIGN.md
+to-do.md
+TODO.md

bioartifact-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+

bioartifact-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `bioartifact` will be documented in this file.
+
+## 0.1.0 - 2026-05-10
+
+Initial release:
+
+- Dependency-free inspection core with JSON-serializable result models.
+- CLI commands for `inspect`, `validate`, `summarize`, `contracts`, `types`,
+  and `validate-manifest`.
+- JSON output by default for every command, with human-readable text available
+  through `--human` or `--output human`.
+- Inspectors for FASTQ, FASTA, SAM, BAM headers, VCF, BED, narrowPeak, GTF/GFF,
+  CSV/TSV, and HTML reports.
+- Contracts for FASTQ, paired FASTQ, sorted/indexed BAM, narrowPeak,
+  differential-expression tables, and valid VCF.
+- Schema-versioned JSON outputs and JSON schemas.
+- Deterministic fixture suite for tests, documentation, and future JOSS examples.
+- Manifest-based workflow output validation.

bioartifact-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+`bioartifact` is early-stage software. Contributions should preserve the core
+scope: lightweight, deterministic, machine-readable inspection and validation of
+bioinformatics artifacts.
+
+## Development Setup
+
+Create an isolated environment and install the package:
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+On systems where Python is not externally managed, `python -m pip install -e
+".[dev]"` is also sufficient.
+
+## Checks
+
+Run tests:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+Run linting:
+
+```bash
+ruff check .
+```
+
+Run formatting before submitting broad edits:
+
+```bash
+ruff format .
+```
+
+## Adding Inspectors
+
+When adding an artifact type:
+
+1. Add conservative extension detection.
+2. Add an independent inspector module.
+3. Return an `ArtifactResult` with deterministic summary fields.
+4. Avoid heavy runtime dependencies unless they are optional extras.
+5. Add valid and invalid fixtures when practical.
+6. Add unit tests and CLI examples.
+
+Inspectors should validate structure and compatibility, not scientific
+interpretation.
+
+## Adding Contracts
+
+When adding a contract:
+
+1. Add a named validator under `src/bioartifact/contracts/`.
+2. Register it in the contract registry.
+3. Emit named `CheckResult` entries with useful messages and remediation hints.
+4. Add a fixture-backed passing test and at least one failing test.
+5. Document the contract in the README and `SKILLS.md`.
+
+## Pull Request Guidance
+
+Keep pull requests focused. Include the command output for tests and linting in
+the PR description. For behavior changes, include before/after JSON examples.
+

bioartifact-0.1.0/LICENSE

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

bioartifact-0.1.0/PKG-INFO

@@ -0,0 +1,389 @@
+Metadata-Version: 2.4
+Name: bioartifact
+Version: 0.1.0
+Summary: Agent-friendly inspection and validation of bioinformatics artifacts.
+Project-URL: Homepage, https://github.com/qchiujunhao/bioartifact
+Project-URL: Issues, https://github.com/qchiujunhao/bioartifact/issues
+Project-URL: Source, https://github.com/qchiujunhao/bioartifact
+Author: Junhao Qiu
+License: MIT License
+        
+        Copyright (c) 2026 Junhao Qiu
+        
+        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.
+License-File: LICENSE
+Keywords: artifacts,bioinformatics,reproducibility,validation,workflow
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Provides-Extra: bio
+Requires-Dist: pysam>=0.22; extra == 'bio'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: manifest
+Requires-Dist: pyyaml>=6.0; extra == 'manifest'
+Provides-Extra: tables
+Requires-Dist: pandas>=2.0; extra == 'tables'
+Description-Content-Type: text/markdown
+
+# bioartifact
+
+`bioartifact` is a lightweight Python package and command-line tool for inspecting and
+validating bioinformatics output files in deterministic, machine-readable form.
+
+The project targets AI agents, workflow systems, benchmark platforms, and
+reproducibility pipelines that need to answer practical questions:
+
+- What kind of artifact was generated?
+- Is the artifact structurally readable?
+- What basic properties does it contain?
+- Does it satisfy a declared contract?
+- Is it usable as input to a downstream workflow step?
+
+The package focuses on structure and compatibility, not biological interpretation.
+
+## Motivation
+
+AI agents, workflow engines, and benchmark systems increasingly need to make
+automated decisions about bioinformatics outputs. Traditional tools are strong
+at format-specific parsing, command-line statistics, or human-readable QC
+reports, but they do not provide a small unified layer for asking: "Was the
+expected artifact produced, is it structurally usable, and does it satisfy the
+contract for the next step?"
+
+`bioartifact` fills that layer with deterministic JSON outputs and named
+contracts. It is designed to complement tools such as `samtools`, `bcftools`,
+FastQC, MultiQC, and workflow engines, not replace them.
+
+## Current Status
+
+This repository contains:
+
+- extension-based artifact detection
+- structured dataclass result models
+- JSON-serializable inspection results
+- a dependency-free CLI built on `argparse`
+- inspectors for FASTQ, FASTA, SAM, BAM headers, VCF, BED, narrowPeak, GTF/GFF,
+  generic CSV/TSV tables, and HTML reports
+- contracts for FASTQ, paired FASTQ, sorted/indexed BAM, narrowPeak,
+  differential-expression tables, and valid VCF
+- schema-versioned JSON outputs
+- CLI discovery commands for supported artifact types and contracts
+- manifest-based workflow output validation
+- directory summarization
+- unit tests and CI configuration
+
+The core has no runtime dependencies. Optional extras can be added for richer
+format support without making the base installation heavy.
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install bioartifact
+```
+
+From a checkout for local development:
+
+```bash
+python -m pip install -e .
+```
+
+For development:
+
+```bash
+python -m pip install -e ".[dev]"
+pre-commit install
+```
+
+Optional richer BAM/SAM support:
+
+```bash
+pip install "bioartifact[bio]"
+```
+
+From a checkout, use `python -m pip install -e ".[bio]"`.
+
+## CLI Examples
+
+Inspect an artifact:
+
+```bash
+bioartifact inspect sample.fastq
+```
+
+Validate a named contract:
+
+```bash
+bioartifact validate peaks.narrowPeak --contract narrowpeak
+```
+
+Validate paired FASTQ files:
+
+```bash
+bioartifact validate sample_R1.fastq.gz --contract paired_fastq --mate sample_R2.fastq.gz
+```
+
+Summarize a directory:
+
+```bash
+bioartifact summarize outputs/ --recursive
+```
+
+List supported contracts and artifact types:
+
+```bash
+bioartifact contracts
+bioartifact types
+```
+
+Validate all expected outputs declared in a manifest:
+
+```bash
+bioartifact validate-manifest workflow_manifest.json
+```
+
+Agent-facing CLI usage guidance is available in [SKILLS.md](SKILLS.md).
+
+## Output Modes
+
+The CLI emits structured JSON by default for every command. This is intentional:
+`bioartifact` is agent-first, and the default output should be deterministic and
+machine-readable regardless of whether a command runs in a terminal, a PTY, CI,
+or a captured subprocess.
+
+This means agents and workflow systems do not need to pass an output-format
+flag. Humans can opt into text output when desired.
+
+For deterministic overrides:
+
+```bash
+bioartifact inspect sample.fastq --output human
+bioartifact inspect sample.fastq --human
+```
+
+The `--json` flag is still accepted for compatibility, but JSON is already the
+default.
+
+## Quickstart With Fixtures
+
+The repository includes small synthetic fixture files that can be used without
+downloading external data:
+
+```bash
+PYTHONPATH=src python -m bioartifact inspect tests/fixtures/variants.vcf.gz
+PYTHONPATH=src python -m bioartifact validate tests/fixtures/peaks.narrowPeak --contract narrowpeak
+PYTHONPATH=src python -m bioartifact validate tests/fixtures/reads_R1.fastq --contract paired_fastq --mate tests/fixtures/reads_R2.fastq
+PYTHONPATH=src python -m bioartifact validate-manifest tests/fixtures/workflow_manifest.pass.json
+```
+
+## Python API
+
+```python
+from bioartifact import inspect_artifact, validate_artifact
+
+artifact = inspect_artifact("sample.vcf.gz")
+print(artifact.to_dict())
+
+contract = validate_artifact("peaks.narrowPeak", "narrowpeak")
+print(contract.to_dict())
+```
+
+## Design Principles
+
+- Agent-first: deterministic, structured, JSON-serializable output.
+- Lightweight: useful with a single command and no workflow engine.
+- Modular: each inspector and contract is independent.
+- Contract-oriented: validate structure, compatibility, and required properties.
+- Conservative: report limitations explicitly instead of inferring scientific meaning.
+
+## Supported Artifact Types
+
+Initial detection and inspection support:
+
+- FASTQ / FASTQ.GZ
+- FASTA / FASTA.GZ
+- SAM
+- BAM header inspection, with optional `pysam` statistics when installed
+- VCF / VCF.GZ
+- BED
+- narrowPeak
+- GTF / GFF / GFF3
+- CSV / TSV
+- HTML / MultiQC HTML
+
+## Inspection Methods
+
+`bioartifact inspect` first detects the artifact type from the filename extension,
+then runs a format-specific structural inspector. Inspectors are conservative:
+they report whether a file is readable and structurally compatible with the
+expected format, but they do not infer biological correctness.
+
+| Artifact type | Detection | Inspection approach | Summary fields |
+| --- | --- | --- | --- |
+| FASTQ / FASTQ.GZ | `.fastq`, `.fq`, `.fastq.gz`, `.fq.gz` | Opens plain text or gzip input, reads four-line FASTQ records, checks `@` headers, `+` separators, incomplete records, and sequence/quality length equality. | record count, base count, min/max/mean read length, gzip flag |
+| FASTA / FASTA.GZ | `.fasta`, `.fa`, `.fna`, and gzip variants | Opens plain text or gzip input, checks that sequence data follows FASTA headers, counts records, and records sequence lengths. | sequence count, base count, min/max/mean sequence length, gzip flag |
+| SAM | `.sam` | Parses SAM text headers and alignment rows, checks that alignment records have at least 11 columns, parses flags, extracts references from `@SQ`, and detects coordinate sorting from `@HD SO:coordinate`. | alignment count, mapped/unmapped counts, references, sort order, flag counts |
+| BAM | `.bam` | Reads the BGZF/gzip BAM header directly, checks the `BAM\1` magic header, parses header text and reference dictionary, detects sort order, and checks for adjacent `.bai`/`.csi` indexes. If `pysam` is installed, indexed BAM read statistics are also attempted. | references, reference names, sort order, index presence, optional mapped/unmapped counts |
+| VCF / VCF.GZ | `.vcf`, `.vcf.gz` | Opens plain text or gzip input, checks metadata/header structure, validates required first 8 VCF columns, detects sample columns, and checks basic record fields such as positive `POS`, non-empty `REF`, and non-empty `ALT`. | metadata line count, variant record count, sample names, sample count, gzip flag |
+| BED | `.bed` | Reads tab-delimited interval rows, ignores comments and browser/track lines, checks at least 3 columns, integer coordinates, non-negative starts, and `end >= start`. | record count, chromosome count, per-chromosome counts, min/max interval width |
+| narrowPeak | `.narrowPeak` | Applies BED coordinate checks plus ENCODE narrowPeak structure checks: at least 10 columns, integer score, valid strand, numeric signal/p/q columns, and integer peak offset. | record count, chromosome counts, min/max width, required column count |
+| GTF | `.gtf` | Parses 9-column GTF rows, validates positive coordinates, summarizes feature types, and extracts `gene_id` and `transcript_id` attributes when present. | record count, feature counts, gene count, transcript count |
+| GFF / GFF3 | `.gff`, `.gff3` | Parses 9-column GFF rows, validates positive coordinates, summarizes feature types, and extracts `ID` attributes for gene-like records where available. | record count, feature counts, gene count, transcript count |
+| CSV / TSV | `.csv`, `.tsv`, `.tab` | Uses Python's CSV parser with delimiter inferred from extension, reads the header, counts rows/columns, tracks empty cells, and rejects rows with inconsistent column counts. | delimiter, row count, column names, column count, missing values, inconsistent rows |
+| HTML / MultiQC HTML | `.html`, `.htm` | Samples the report text, checks for an HTML root/doctype marker, extracts the `<title>`, and detects MultiQC-like reports by searching for `multiqc`. | title, MultiQC flag, sampled byte count |
+
+The current BAM inspector intentionally keeps the default installation light by
+parsing the BAM header without requiring `pysam`. Installing `bioartifact[bio]`
+enables optional `pysam`-based statistics for indexed BAM files.
+
+## Supported Contracts
+
+- `fastq`
+- `paired_fastq`
+- `sorted_bam`
+- `indexed_bam`
+- `narrowpeak`
+- `de_table`
+- `valid_vcf`
+
+## Contract Reference
+
+| Contract | Expected input | Behavior | Common limitation | Example |
+| --- | --- | --- | --- | --- |
+| `fastq` | FASTQ or FASTQ.GZ | Checks readability, gzip integrity when applicable, record presence, and sequence/quality length equality. | Does not run per-base quality QC. | `bioartifact validate reads.fastq.gz --contract fastq` |
+| `paired_fastq` | R1 FASTQ plus `--mate` R2 FASTQ | Checks both files, read-count synchronization, and normalized read ID matching. | Does not infer mates automatically. | `bioartifact validate R1.fastq.gz --contract paired_fastq --mate R2.fastq.gz` |
+| `sorted_bam` | BAM or SAM | Checks readability and whether the alignment header declares coordinate sorting. | Does not prove record-level sort order without deeper parsing. | `bioartifact validate aligned.bam --contract sorted_bam` |
+| `indexed_bam` | BAM | Checks readability and adjacent `.bai` or `.csi` presence. | Does not verify full index correctness. | `bioartifact validate aligned.bam --contract indexed_bam` |
+| `narrowpeak` | narrowPeak | Checks required 10-column structure and interval coordinates. | Does not judge peak-calling quality. | `bioartifact validate peaks.narrowPeak --contract narrowpeak` |
+| `de_table` | CSV or TSV | Checks required DE columns, p-value ranges, and duplicate/empty genes. | Assumes exact column names. | `bioartifact validate de_table.tsv --contract de_table` |
+| `valid_vcf` | VCF or VCF.GZ | Checks header, required columns, basic records, and sample column structure. | Does not replace `bcftools` validation. | `bioartifact validate variants.vcf.gz --contract valid_vcf` |
+
+## Manifest Validation
+
+Use `validate-manifest` when a workflow run should produce multiple expected
+artifacts. Relative paths are resolved against the manifest directory unless
+`--base-dir` is provided.
+
+Minimal JSON manifest:
+
+```json
+{
+  "outputs": [
+    {
+      "name": "peaks",
+      "path": "peaks.narrowPeak",
+      "type": "narrowPeak",
+      "contract": "narrowpeak"
+    },
+    {
+      "name": "paired_reads",
+      "path": "reads_R1.fastq.gz",
+      "type": "fastq",
+      "contract": "paired_fastq",
+      "mate": "reads_R2.fastq.gz"
+    }
+  ]
+}
+```
+
+Run:
+
+```bash
+bioartifact validate-manifest workflow_manifest.json
+```
+
+YAML manifests are supported when `PyYAML` is installed, for example with
+`python -m pip install -e ".[manifest]"`.
+
+## JSON Output Reference
+
+All structured CLI outputs include `schema_version`. The current schema version
+is `1.0.0`.
+
+- Artifact inspection schema: [schemas/artifact_result.schema.json](schemas/artifact_result.schema.json)
+- Contract validation schema: [schemas/contract_result.schema.json](schemas/contract_result.schema.json)
+- Manifest validation schema: [schemas/manifest_result.schema.json](schemas/manifest_result.schema.json)
+
+Schema files are intended to be part of the user-facing interface for the `1.x`
+line. Additive fields may be introduced in minor releases; breaking output
+changes require a new major schema version.
+
+## CLI Exit Codes
+
+- `0`: the requested inspection, validation, summary, discovery, or manifest
+  validation succeeded.
+- `1`: inspection or validation failed, a manifest did not pass, or the input
+  path/manifest was invalid.
+
+Warnings do not cause a non-zero exit code unless a required structural check or
+contract check fails.
+
+## Development
+
+Run the standard-library test suite:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+Run the configured developer checks after installing dev dependencies:
+
+```bash
+ruff check .
+pytest
+```
+
+## Releasing
+
+PyPI publishing is handled by GitHub Actions through PyPI Trusted Publishing.
+For the first release, create a pending publisher on PyPI with:
+
+- PyPI project name: `bioartifact`
+- Owner: `qchiujunhao`
+- Repository name: `bioartifact`
+- Workflow name: `release.yml`
+- Environment name: `pypi`
+
+After the pending publisher is configured, run the `Release` workflow manually
+from GitHub Actions or push a `v*` tag for future releases.
+
+## Reproducible Fixtures
+
+The repository includes a small fixture suite under `tests/fixtures/` with
+versioned FASTA, FASTQ, FASTQ.GZ, SAM, BAM, VCF, VCF.GZ, BED, narrowPeak, GTF,
+TSV, and HTML report examples. These files are synthetic but structurally valid,
+small enough for CI, and documented with provenance notes so they can support
+examples in documentation and a future JOSS paper.
+
+Binary fixtures are deterministic and can be regenerated with:
+
+```bash
+python tests/fixtures/scripts/build_binary_fixtures.py
+```