bioartifact 0.1.0__py3-none-any.whl

bioartifact/__init__.py

@@ -0,0 +1,25 @@
+"""Agent-friendly inspection and validation of bioinformatics artifacts."""
+
+from bioartifact.contracts import available_contracts, validate_artifact
+from bioartifact.detection import detect_artifact_type
+from bioartifact.inspectors import inspect_artifact
+from bioartifact.manifest import validate_manifest
+from bioartifact.metadata import artifact_type_details, contract_details
+from bioartifact.models import ArtifactResult, CheckResult, ContractResult
+from bioartifact.summarize import summarize_directory
+
+__all__ = [
+    "ArtifactResult",
+    "CheckResult",
+    "ContractResult",
+    "available_contracts",
+    "artifact_type_details",
+    "contract_details",
+    "detect_artifact_type",
+    "inspect_artifact",
+    "summarize_directory",
+    "validate_artifact",
+    "validate_manifest",
+]
+
+__version__ = "0.1.0"

bioartifact/__main__.py

@@ -0,0 +1,4 @@
+from bioartifact.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bioartifact/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface package."""

bioartifact/cli/main.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from bioartifact.contracts import available_contracts, validate_artifact
+from bioartifact.inspectors import inspect_artifact
+from bioartifact.json import dumps_json
+from bioartifact.manifest import validate_manifest
+from bioartifact.metadata import artifact_type_details, contract_details
+from bioartifact.summarize import summarize_directory
+
+
+def _print_payload(payload: dict[str, Any], args: argparse.Namespace) -> None:
+    if _should_emit_json(args):
+        print(dumps_json(payload))
+        return
+
+    for key, value in payload.items():
+        if isinstance(value, list):
+            print(f"{key}:")
+            for item in value:
+                print(f"  - {item}")
+        elif isinstance(value, dict):
+            print(f"{key}:")
+            for nested_key, nested_value in value.items():
+                print(f"  {nested_key}: {nested_value}")
+        else:
+            print(f"{key}: {value}")
+
+
+def _should_emit_json(args: argparse.Namespace) -> bool:
+    if getattr(args, "human", False):
+        return False
+    if getattr(args, "json", False):
+        return True
+    return getattr(args, "output", "json") != "human"
+
+
+def _inspect(args: argparse.Namespace) -> int:
+    result = inspect_artifact(args.path, artifact_type=args.type)
+    _print_payload(result.to_dict(), args)
+    return 0 if result.valid else 1
+
+
+def _validate(args: argparse.Namespace) -> int:
+    result = validate_artifact(args.path, args.contract, mate=args.mate)
+    _print_payload(result.to_dict(), args)
+    return 0 if result.passed else 1
+
+
+def _summarize(args: argparse.Namespace) -> int:
+    result = summarize_directory(args.path, recursive=args.recursive)
+    _print_payload(result, args)
+    return 0 if result["valid"] else 1
+
+
+def _contracts(args: argparse.Namespace) -> int:
+    _print_payload(contract_details(), args)
+    return 0
+
+
+def _types(args: argparse.Namespace) -> int:
+    _print_payload(artifact_type_details(), args)
+    return 0
+
+
+def _validate_manifest(args: argparse.Namespace) -> int:
+    result = validate_manifest(args.path, base_dir=args.base_dir)
+    _print_payload(result, args)
+    return 0 if result["passed"] else 1
+
+
+def _add_output_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--output",
+        choices=["json", "human"],
+        default="json",
+        help="output mode; defaults to JSON",
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="emit structured JSON output; this is the default"
+    )
+    parser.add_argument("--human", action="store_true", help="force human-readable output")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bioartifact",
+        description="Inspect and validate bioinformatics artifacts.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    inspect_parser = subparsers.add_parser("inspect", help="inspect one artifact")
+    inspect_parser.add_argument("path", help="artifact path")
+    inspect_parser.add_argument("--type", help="override artifact type detection")
+    _add_output_arguments(inspect_parser)
+    inspect_parser.set_defaults(func=_inspect)
+
+    validate_parser = subparsers.add_parser("validate", help="validate an artifact contract")
+    validate_parser.add_argument("path", help="artifact path")
+    validate_parser.add_argument(
+        "--contract",
+        required=True,
+        choices=available_contracts(),
+        help="contract name",
+    )
+    validate_parser.add_argument("--mate", help="mate FASTQ path for paired_fastq")
+    _add_output_arguments(validate_parser)
+    validate_parser.set_defaults(func=_validate)
+
+    summarize_parser = subparsers.add_parser("summarize", help="summarize a directory")
+    summarize_parser.add_argument("path", help="directory path")
+    summarize_parser.add_argument("--recursive", action="store_true", help="scan recursively")
+    _add_output_arguments(summarize_parser)
+    summarize_parser.set_defaults(func=_summarize)
+
+    contracts_parser = subparsers.add_parser("contracts", help="list supported contracts")
+    _add_output_arguments(contracts_parser)
+    contracts_parser.set_defaults(func=_contracts)
+
+    types_parser = subparsers.add_parser("types", help="list supported artifact types")
+    _add_output_arguments(types_parser)
+    types_parser.set_defaults(func=_types)
+
+    manifest_parser = subparsers.add_parser(
+        "validate-manifest",
+        help="validate expected workflow outputs from a JSON or YAML manifest",
+    )
+    manifest_parser.add_argument("path", help="manifest path")
+    manifest_parser.add_argument(
+        "--base-dir",
+        help="base directory for relative output paths; defaults to the manifest directory",
+    )
+    _add_output_arguments(manifest_parser)
+    manifest_parser.set_defaults(func=_validate_manifest)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

bioartifact/contracts/__init__.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from bioartifact.contracts.alignment import validate_indexed_bam, validate_sorted_bam
+from bioartifact.contracts.fastq import validate_fastq, validate_paired_fastq
+from bioartifact.contracts.intervals import validate_narrowpeak
+from bioartifact.contracts.tables import validate_de_table
+from bioartifact.contracts.vcf import validate_valid_vcf
+from bioartifact.models import ContractResult, failed
+
+ContractValidator = Callable[..., ContractResult]
+
+CONTRACTS: dict[str, ContractValidator] = {
+    "de_table": validate_de_table,
+    "fastq": validate_fastq,
+    "indexed_bam": validate_indexed_bam,
+    "narrowpeak": validate_narrowpeak,
+    "paired_fastq": validate_paired_fastq,
+    "sorted_bam": validate_sorted_bam,
+    "valid_vcf": validate_valid_vcf,
+}
+
+
+def available_contracts() -> list[str]:
+    """Return supported contract names."""
+
+    return sorted(CONTRACTS)
+
+
+def validate_artifact(path: str | Path, contract_name: str, **kwargs: Any) -> ContractResult:
+    """Validate one artifact against a named contract."""
+
+    validator = CONTRACTS.get(contract_name)
+    if validator is None:
+        return ContractResult(
+            contract_name=contract_name,
+            passed=False,
+            path=str(path),
+            checks=[
+                failed(
+                    "known_contract",
+                    f"unknown contract '{contract_name}'",
+                    remediation="Run `bioartifact contracts` and choose one of the listed contract names.",
+                    available_contracts=available_contracts(),
+                )
+            ],
+            errors=[f"unknown contract '{contract_name}'"],
+        )
+    return validator(Path(path), **kwargs)

bioartifact/contracts/alignment.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from bioartifact.contracts.common import result
+from bioartifact.inspectors import inspect_artifact
+from bioartifact.models import ContractResult, failed, passed
+
+
+def validate_sorted_bam(path: Path, **_: object) -> ContractResult:
+    artifact = inspect_artifact(path)
+    checks = [
+        passed("readable", "alignment artifact is readable")
+        if artifact.valid
+        else failed(
+            "readable",
+            "alignment artifact is not readable",
+            remediation="Regenerate the alignment file or inspect the upstream aligner output.",
+            errors=artifact.errors,
+        ),
+    ]
+
+    if artifact.artifact_type not in {"bam", "sam"}:
+        checks.append(
+            failed(
+                "artifact_type",
+                "sorted_bam contract expects a BAM or SAM artifact",
+                remediation="Provide a `.bam` or `.sam` alignment file for this contract.",
+                artifact_type=artifact.artifact_type,
+            )
+        )
+    else:
+        checks.append(passed("artifact_type", "artifact is an alignment file"))
+
+    if artifact.summary.get("sorted") is True:
+        checks.append(passed("coordinate_sorted", "alignment is coordinate sorted"))
+    else:
+        checks.append(
+            failed(
+                "coordinate_sorted",
+                "alignment is not declared coordinate sorted",
+                remediation="Sort the alignment by coordinate, for example with `samtools sort`, then rerun validation.",
+                sort_order=artifact.summary.get("sort_order"),
+            )
+        )
+
+    return result(
+        "sorted_bam",
+        checks,
+        path=str(path),
+        artifact_type=artifact.artifact_type,
+        warnings=artifact.warnings,
+        errors=artifact.errors,
+    )
+
+
+def validate_indexed_bam(path: Path, **_: object) -> ContractResult:
+    artifact = inspect_artifact(path)
+    checks = [
+        passed("readable", "BAM is readable")
+        if artifact.valid
+        else failed(
+            "readable",
+            "BAM is not readable",
+            remediation="Regenerate the BAM file or check that it is BGZF-compressed BAM.",
+            errors=artifact.errors,
+        ),
+    ]
+
+    if artifact.artifact_type != "bam":
+        checks.append(
+            failed(
+                "artifact_type",
+                "indexed_bam contract expects a BAM artifact",
+                remediation="Provide a `.bam` file for the indexed_bam contract.",
+                artifact_type=artifact.artifact_type,
+            )
+        )
+    else:
+        checks.append(passed("artifact_type", "artifact is a BAM file"))
+
+    if artifact.summary.get("index_present") is True:
+        checks.append(passed("index_present", "BAM index was found"))
+    else:
+        checks.append(
+            failed(
+                "index_present",
+                "no BAM index was found next to the BAM file",
+                remediation="Create an index with `samtools index aligned.bam` or provide an adjacent `.bai`/`.csi` file.",
+            )
+        )
+
+    return result(
+        "indexed_bam",
+        checks,
+        path=str(path),
+        artifact_type=artifact.artifact_type,
+        warnings=artifact.warnings,
+        errors=artifact.errors,
+    )

bioartifact/contracts/common.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from bioartifact.models import CheckResult, ContractResult
+
+
+def result(
+    contract_name: str,
+    checks: Iterable[CheckResult],
+    *,
+    path: str | None = None,
+    artifact_type: str | None = None,
+    warnings: list[str] | None = None,
+    errors: list[str] | None = None,
+) -> ContractResult:
+    check_list = list(checks)
+    return ContractResult(
+        contract_name=contract_name,
+        passed=all(check.status != "fail" for check in check_list),
+        checks=check_list,
+        path=path,
+        artifact_type=artifact_type,
+        warnings=warnings or [],
+        errors=errors or [],
+    )

bioartifact/contracts/fastq.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from itertools import zip_longest
+from pathlib import Path
+
+from bioartifact.contracts.common import result
+from bioartifact.inspectors.fastq import inspect_fastq, normalize_fastq_read_id
+from bioartifact.io import open_text
+from bioartifact.models import ContractResult, failed, passed
+
+
+def validate_fastq(path: Path, **_: object) -> ContractResult:
+    artifact = inspect_fastq(path)
+    checks = [
+        passed("readable", "FASTQ is readable")
+        if artifact.valid
+        else failed(
+            "readable",
+            "FASTQ is not structurally valid",
+            remediation="Regenerate or repair the FASTQ file before using it downstream.",
+            errors=artifact.errors,
+        ),
+        passed("records_present", "FASTQ contains records", records=artifact.summary["records"])
+        if artifact.summary["records"] > 0
+        else failed(
+            "records_present",
+            "FASTQ contains no records",
+            remediation="Check that the workflow wrote reads to the expected FASTQ path.",
+        ),
+    ]
+
+    if path.name.lower().endswith(".gz"):
+        if artifact.summary.get("gzip"):
+            checks.append(passed("valid_gzip", "gzip encoding is valid"))
+        else:
+            checks.append(
+                failed(
+                    "valid_gzip",
+                    "file extension indicates gzip but gzip magic is absent",
+                    remediation="Recompress the file with gzip or correct the filename extension.",
+                )
+            )
+
+    if artifact.valid:
+        checks.append(passed("sequence_quality_lengths", "all sequence and quality lengths match"))
+    else:
+        length_errors = [
+            error for error in artifact.errors if "sequence and quality lengths differ" in error
+        ]
+        if length_errors:
+            checks.append(
+                failed(
+                    "sequence_quality_lengths",
+                    "one or more FASTQ records have mismatched sequence and quality lengths",
+                    remediation="Regenerate the FASTQ or trim/filter with a tool that preserves sequence and quality synchronization.",
+                    examples=length_errors[:5],
+                )
+            )
+
+    return result(
+        "fastq",
+        checks,
+        path=str(path),
+        artifact_type=artifact.artifact_type,
+        warnings=artifact.warnings,
+        errors=artifact.errors,
+    )
+
+
+def _iter_fastq_ids(path: Path):
+    with open_text(path) as handle:
+        while True:
+            header = handle.readline()
+            if not header:
+                break
+            if not header.strip():
+                break
+            sequence = handle.readline()
+            plus = handle.readline()
+            quality = handle.readline()
+            if not sequence or not plus or not quality:
+                break
+            yield normalize_fastq_read_id(header)
+
+
+def validate_paired_fastq(
+    path: Path, mate: str | Path | None = None, **_: object
+) -> ContractResult:
+    if mate is None:
+        return result(
+            "paired_fastq",
+            [
+                failed(
+                    "mate_provided",
+                    "paired_fastq contract requires --mate",
+                    remediation="Pass the second FASTQ file with `--mate`.",
+                )
+            ],
+            path=str(path),
+            artifact_type="fastq",
+        )
+
+    mate_path = Path(mate)
+    first = inspect_fastq(path)
+    second = inspect_fastq(mate_path)
+    checks = [
+        passed("first_readable", "first FASTQ is valid")
+        if first.valid
+        else failed(
+            "first_readable",
+            "first FASTQ is invalid",
+            remediation="Repair or regenerate the first mate FASTQ.",
+            errors=first.errors,
+        ),
+        passed("second_readable", "second FASTQ is valid")
+        if second.valid
+        else failed(
+            "second_readable",
+            "second FASTQ is invalid",
+            remediation="Repair or regenerate the second mate FASTQ.",
+            errors=second.errors,
+        ),
+    ]
+
+    first_records = first.summary.get("records", 0)
+    second_records = second.summary.get("records", 0)
+    if first_records == second_records:
+        checks.append(passed("synchronized_read_counts", "FASTQ files contain equal read counts"))
+    else:
+        checks.append(
+            failed(
+                "synchronized_read_counts",
+                "FASTQ files contain different read counts",
+                remediation="Recreate the paired FASTQ files from the same synchronized filtering step.",
+                first_records=first_records,
+                second_records=second_records,
+            )
+        )
+
+    if first.valid and second.valid:
+        mismatches = []
+        compared = 0
+        for compared, (first_id, second_id) in enumerate(
+            zip_longest(_iter_fastq_ids(path), _iter_fastq_ids(mate_path)),
+            start=1,
+        ):
+            if first_id != second_id:
+                mismatches.append(
+                    {"record": compared, "first_id": first_id, "second_id": second_id}
+                )
+                if len(mismatches) >= 10:
+                    break
+        if mismatches:
+            checks.append(
+                failed(
+                    "matching_read_ids",
+                    "paired FASTQ read IDs differ",
+                    remediation="Verify that R1 and R2 files belong to the same sample and filtering step.",
+                    examples=mismatches,
+                )
+            )
+        else:
+            checks.append(
+                passed("matching_read_ids", "paired FASTQ read IDs match", compared=compared)
+            )
+
+    return result(
+        "paired_fastq",
+        checks,
+        path=str(path),
+        artifact_type="fastq",
+        warnings=first.warnings + second.warnings,
+        errors=first.errors + second.errors,
+    )

bioartifact/contracts/intervals.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from bioartifact.contracts.common import result
+from bioartifact.inspectors.bed import inspect_narrowpeak
+from bioartifact.models import ContractResult, failed, passed
+
+
+def validate_narrowpeak(path: Path, **_: object) -> ContractResult:
+    artifact = inspect_narrowpeak(path)
+    checks = [
+        passed("readable", "narrowPeak file is readable")
+        if artifact.valid
+        else failed(
+            "readable",
+            "narrowPeak file is invalid",
+            remediation="Regenerate the peak caller output or validate that the file is tab-delimited narrowPeak.",
+            errors=artifact.errors,
+        ),
+    ]
+
+    records = artifact.summary.get("records", 0)
+    if records:
+        checks.append(passed("records_present", "narrowPeak contains records", records=records))
+    else:
+        checks.append(
+            failed(
+                "records_present",
+                "narrowPeak contains no records",
+                remediation="Check that peak calling completed and wrote peaks to the expected path.",
+            )
+        )
+
+    column_errors = [error for error in artifact.errors if "fewer than 10" in error]
+    if column_errors:
+        checks.append(
+            failed(
+                "required_columns",
+                "one or more rows have fewer than 10 columns",
+                remediation="Use a narrowPeak output, not a BED3/BED6 peak file, or choose a BED-oriented contract.",
+                examples=column_errors,
+            )
+        )
+    else:
+        checks.append(passed("required_columns", "all rows contain required narrowPeak columns"))
+
+    coordinate_errors = [
+        error
+        for error in artifact.errors
+        if "coordinate" in error or "end before start" in error or "negative start" in error
+    ]
+    if coordinate_errors:
+        checks.append(
+            failed(
+                "coordinates_valid",
+                "one or more rows contain invalid genomic coordinates",
+                remediation="Ensure starts are non-negative integers and ends are greater than or equal to starts.",
+                examples=coordinate_errors,
+            )
+        )
+    else:
+        checks.append(passed("coordinates_valid", "all genomic coordinates are valid"))
+
+    return result(
+        "narrowpeak",
+        checks,
+        path=str(path),
+        artifact_type=artifact.artifact_type,
+        warnings=artifact.warnings,
+        errors=artifact.errors,
+    )