gseek 0.2.0__py3-none-any.whl

gseek/__init__.py

@@ -0,0 +1,198 @@
+"""gseek: unified, reproducible DNA alignment infrastructure."""
+
+from __future__ import annotations
+
+from gseek.adapter import (
+    AlignmentAdapter,
+    AlignPlan,
+    AlignRequest,
+    DistanceAdapter,
+    DistanceRequest,
+    IndexPlan,
+    IndexRequest,
+    ParseContext,
+    PlanContext,
+)
+from gseek.api import (
+    align,
+    backends,
+    distance,
+    find,
+    find_backends,
+    get_backend,
+    register_adapter,
+    replay,
+    verify,
+)
+from gseek.capabilities import (
+    BackendSpec,
+    Capabilities,
+    ToolchainProbe,
+    ToolRequirement,
+)
+from gseek.errors import (
+    CacheError,
+    ConfigError,
+    DuplicateIdError,
+    ExecutionError,
+    GseekError,
+    IndexBuildError,
+    IndexLockError,
+    InputError,
+    ManifestError,
+    ParseError,
+    ReplayMismatchError,
+    ToolNotFoundError,
+    ToolVersionError,
+    UnsupportedFeatureError,
+    UsageError,
+    render_error,
+)
+from gseek.execution import (
+    CommandPlan,
+    Executor,
+    ProcessResult,
+    RunWorkspace,
+    ToolProbe,
+    ToolResolver,
+    create_workspace,
+)
+from gseek.index import IndexPolicy, IndexStore, compute_index_key, default_cache_root
+from gseek.model import (
+    AlignmentRecord,
+    AlignmentResult,
+    AlignmentStats,
+    CommandRecord,
+    DistanceRecord,
+    DistanceResult,
+    DistanceStats,
+    FileRef,
+    IndexRef,
+    InputRef,
+    Issue,
+    QuerySummary,
+    RunManifest,
+    TargetSummary,
+    ToolRef,
+    build_alignment_stats,
+)
+from gseek.provenance import (
+    alignment_result_hash,
+    canonical_json,
+    distance_result_hash,
+    gseek_version,
+    read_manifest,
+    recipe_hash,
+    result_hash,
+    sha256_file,
+    verify_manifest,
+    write_manifest,
+)
+from gseek.replay import ReplayResult
+from gseek.types import (
+    ALIGNMENT_SCHEMA,
+    DISTANCE_SCHEMA,
+    INDEX_SCHEMA,
+    RUN_SCHEMA,
+    IndexScope,
+    InputKind,
+    Interval,
+    JsonValue,
+    Molecule,
+    OutputKind,
+    RunStatus,
+    Strand,
+)
+from gseek.version import __version__
+
+__all__ = [
+    "ALIGNMENT_SCHEMA",
+    "DISTANCE_SCHEMA",
+    "INDEX_SCHEMA",
+    "RUN_SCHEMA",
+    "AlignPlan",
+    "AlignRequest",
+    "AlignmentAdapter",
+    "AlignmentRecord",
+    "AlignmentResult",
+    "AlignmentStats",
+    "BackendSpec",
+    "CacheError",
+    "Capabilities",
+    "CommandPlan",
+    "CommandRecord",
+    "ConfigError",
+    "DistanceAdapter",
+    "DistanceRecord",
+    "DistanceRequest",
+    "DistanceResult",
+    "DistanceStats",
+    "DuplicateIdError",
+    "ExecutionError",
+    "Executor",
+    "FileRef",
+    "GseekError",
+    "IndexBuildError",
+    "IndexLockError",
+    "IndexPlan",
+    "IndexPolicy",
+    "IndexRef",
+    "IndexRequest",
+    "IndexScope",
+    "IndexStore",
+    "InputError",
+    "InputKind",
+    "InputRef",
+    "Interval",
+    "Issue",
+    "JsonValue",
+    "ManifestError",
+    "Molecule",
+    "OutputKind",
+    "ParseContext",
+    "ParseError",
+    "PlanContext",
+    "ProcessResult",
+    "QuerySummary",
+    "ReplayMismatchError",
+    "ReplayResult",
+    "RunManifest",
+    "RunStatus",
+    "RunWorkspace",
+    "Strand",
+    "TargetSummary",
+    "ToolNotFoundError",
+    "ToolProbe",
+    "ToolRef",
+    "ToolRequirement",
+    "ToolResolver",
+    "ToolVersionError",
+    "ToolchainProbe",
+    "UnsupportedFeatureError",
+    "UsageError",
+    "__version__",
+    "align",
+    "alignment_result_hash",
+    "backends",
+    "build_alignment_stats",
+    "canonical_json",
+    "compute_index_key",
+    "create_workspace",
+    "default_cache_root",
+    "distance",
+    "distance_result_hash",
+    "find",
+    "find_backends",
+    "get_backend",
+    "gseek_version",
+    "read_manifest",
+    "recipe_hash",
+    "register_adapter",
+    "render_error",
+    "replay",
+    "result_hash",
+    "sha256_file",
+    "verify",
+    "verify_manifest",
+    "write_manifest",
+]

gseek/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m gseek`` entry point."""
+
+from __future__ import annotations
+
+from gseek.cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

gseek/adapter.py

@@ -0,0 +1,292 @@
+"""Adapter protocol: pure planning and parsing, no subprocesses.
+
+An adapter turns a declarative request into commands plus a parser. The runner
+owns execution, index publication, provenance, and result construction. This
+split is what makes adapters testable without installing external tools.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from gseek.capabilities import BackendSpec, ToolchainProbe, ToolRequirement, supports
+from gseek.errors import ToolNotFoundError, ToolVersionError, UnsupportedFeatureError
+from gseek.execution import CommandPlan, ToolProbe, ToolResolver
+from gseek.index import IndexPolicy
+from gseek.io import detect_input_kind
+from gseek.model import AlignmentRecord, IndexRef, InputRef, ToolRef
+from gseek.provenance import semantic_params
+from gseek.types import InputKind, JsonValue, Molecule, OutputKind
+
+
+@dataclass(frozen=True, slots=True)
+class AlignRequest:
+    """One query (or read pair) against one target set."""
+
+    query: tuple[Path, ...]
+    target: tuple[Path, ...]
+    query_kind: InputKind | None = None
+    paired: bool = False
+    params: Mapping[str, JsonValue] = field(default_factory=dict)
+    threads: int = 1
+    timeout_s: float | None = None
+    index_policy: IndexPolicy = IndexPolicy.AUTO
+    target_filter: frozenset[str] | None = None
+    work_dir: Path | None = None
+    keep_work: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.query:
+            raise UnsupportedFeatureError("at least one query file is required")
+        if not self.target:
+            raise UnsupportedFeatureError("at least one target file is required")
+        if self.paired and len(self.query) != 2:
+            raise UnsupportedFeatureError("paired mode requires exactly two query files")
+        if not self.paired and len(self.query) != 1:
+            raise UnsupportedFeatureError("single-end mode requires exactly one query file")
+        if self.threads < 1:
+            raise UnsupportedFeatureError(f"threads must be >= 1, got {self.threads}")
+        if self.timeout_s is not None and self.timeout_s <= 0:
+            raise UnsupportedFeatureError(f"timeout_s must be positive, got {self.timeout_s}")
+
+    @property
+    def resolved_query_kind(self) -> InputKind:
+        return self.query_kind or detect_input_kind(self.query[0])
+
+
+@dataclass(frozen=True, slots=True)
+class DistanceRequest:
+    """One or more queries against a sketch/distance reference set."""
+
+    query: tuple[Path, ...]
+    reference: tuple[Path, ...]
+    query_kind: InputKind | None = None
+    params: Mapping[str, JsonValue] = field(default_factory=dict)
+    threads: int = 1
+    timeout_s: float | None = None
+    index_policy: IndexPolicy = IndexPolicy.AUTO
+    external_reference: bool = False
+    work_dir: Path | None = None
+    keep_work: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.query:
+            raise UnsupportedFeatureError("at least one query file is required")
+        if not self.reference:
+            raise UnsupportedFeatureError("at least one reference file is required")
+        if self.threads < 1:
+            raise UnsupportedFeatureError(f"threads must be >= 1, got {self.threads}")
+        if self.external_reference and len(self.reference) != 1:
+            raise UnsupportedFeatureError(
+                "external_reference requires exactly one pre-built reference file"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class IndexRequest:
+    target: tuple[Path, ...]
+    params: Mapping[str, JsonValue] = field(default_factory=dict)
+    threads: int = 1
+    force: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class PlanContext:
+    """Paths and immutable context available while planning commands."""
+
+    workspace: Path
+    index_dir: Path | None = None
+    threads: int = 1
+    query_refs: tuple[InputRef, ...] = ()
+    target_refs: tuple[InputRef, ...] = ()
+
+    def path(self, *parts: str) -> Path:
+        target = self.workspace.joinpath(*parts)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        return target
+
+
+@dataclass(frozen=True, slots=True)
+class IndexPlan:
+    """Commands that build an index plus the expected entry/artifacts."""
+
+    commands: tuple[CommandPlan, ...]
+    entry: str
+    artifacts: tuple[str, ...] = ()
+    params: Mapping[str, JsonValue] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class AlignPlan:
+    """Commands that perform one alignment plus how to parse their output."""
+
+    commands: tuple[CommandPlan, ...]
+    stream: bool = False
+    result_files: tuple[Path, ...] = ()
+    extra: Mapping[str, JsonValue] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class ParseContext:
+    """Everything a parser needs to normalize one result set."""
+
+    request: AlignRequest
+    plan: AlignPlan
+    workspace: Path
+    index: IndexRef | None = None
+    tools: tuple[ToolRef, ...] = ()
+
+
+@runtime_checkable
+class AlignmentAdapter(Protocol):
+    """A backend that produces :class:`AlignmentRecord` rows."""
+
+    spec: BackendSpec
+
+    def probe(self, resolver: ToolResolver, *, strict: bool = False) -> ToolchainProbe: ...
+
+    def semantic_params(self, params: Mapping[str, JsonValue]) -> dict[str, JsonValue]: ...
+
+    def plan_index(self, request: IndexRequest, ctx: PlanContext) -> IndexPlan | None: ...
+
+    def plan_align(
+        self,
+        request: AlignRequest,
+        index: IndexRef | None,
+        ctx: PlanContext,
+    ) -> AlignPlan: ...
+
+    def parse_align(
+        self,
+        ctx: ParseContext,
+        stream: Iterable[str] | None = None,
+    ) -> Iterator[AlignmentRecord]: ...
+
+
+@runtime_checkable
+class DistanceAdapter(Protocol):
+    """A backend that produces distance/containment rows."""
+
+    spec: BackendSpec
+
+    def probe(self, resolver: ToolResolver, *, strict: bool = False) -> ToolchainProbe: ...
+
+    def semantic_params(self, params: Mapping[str, JsonValue]) -> dict[str, JsonValue]: ...
+
+    def plan_index(self, request: IndexRequest, ctx: PlanContext) -> IndexPlan | None: ...
+
+    def plan_distance(
+        self,
+        request: DistanceRequest,
+        index: IndexRef | None,
+        ctx: PlanContext,
+    ) -> AlignPlan: ...
+
+    def parse_distance(
+        self,
+        ctx: ParseContext,
+        stream: Iterable[str] | None = None,
+    ) -> Iterator[object]: ...
+
+
+class BaseAdapter:
+    """Shared validation/probing helpers for concrete adapters."""
+
+    spec: BackendSpec
+
+    def probe(self, resolver: ToolResolver, *, strict: bool = False) -> ToolchainProbe:
+        """Resolve and version-check every declared tool."""
+        probes = []
+        failed: list[tuple[ToolRequirement, ToolProbe]] = []
+        for requirement in self.spec.tools:
+            probe = resolver.probe(requirement, strict=False)
+            probes.append(probe)
+            if not probe.ok and not requirement.optional:
+                failed.append((requirement, probe))
+        failures = [f"{probe.name}: {probe.error or 'unavailable'}" for _, probe in failed]
+        ok = not failures
+        result = ToolchainProbe(
+            backend=self.spec.name,
+            tools=tuple(probes),
+            ok=ok,
+            error="; ".join(failures),
+        )
+        if strict and failed:
+            missing = any(probe.path is None for _, probe in failed)
+            error_type = ToolNotFoundError if missing else ToolVersionError
+            hint = "; ".join(requirement.hint for requirement, _ in failed if requirement.hint)
+            raise error_type(
+                f"backend {self.spec.name!r} is unavailable: {result.error}",
+                hint=hint,
+                context={"backend": self.spec.name},
+            )
+        return result
+
+    def semantic_params(self, params: Mapping[str, JsonValue]) -> dict[str, JsonValue]:
+        return semantic_params(params)
+
+    def plan_index(self, request: IndexRequest, ctx: PlanContext) -> IndexPlan | None:
+        if self.spec.capabilities.index_scope.value != "none":
+            raise NotImplementedError(f"{self.spec.name} declares an index but does not plan one")
+        return None
+
+    def check_align_request(self, request: AlignRequest) -> InputKind:
+        """Validate input kind/paired/preset against the capability declaration."""
+        query_kind = request.resolved_query_kind
+        if not supports(
+            self.spec,
+            input_kind=query_kind,
+            output_kind=OutputKind.ALIGNMENT,
+            paired=request.paired,
+        ):
+            raise UnsupportedFeatureError(
+                f"backend {self.spec.name!r} does not support "
+                f"input={query_kind.value}, paired={request.paired}",
+                context={"backend": self.spec.name, "input": query_kind.value},
+            )
+        preset = request.params.get("preset")
+        if (
+            preset is not None
+            and self.spec.capabilities.presets
+            and str(preset) not in self.spec.capabilities.presets
+        ):
+            raise UnsupportedFeatureError(
+                f"unknown preset {preset!r} for backend {self.spec.name!r}; "
+                f"expected one of {self.spec.capabilities.presets}",
+                context={"backend": self.spec.name, "preset": str(preset)},
+            )
+        return query_kind
+
+    def describe(self) -> dict[str, JsonValue]:
+        from gseek.provenance import to_jsonable
+
+        return to_jsonable(self.spec)
+
+
+def request_molecule(params: Mapping[str, JsonValue]) -> Molecule:
+    raw = str(params.get("molecule", Molecule.DNA.value)).lower()
+    try:
+        return Molecule(raw)
+    except ValueError as exc:
+        raise UnsupportedFeatureError(
+            f"unknown molecule {raw!r}",
+            context={"molecule": raw},
+        ) from exc
+
+
+__all__ = [
+    "AlignPlan",
+    "AlignRequest",
+    "AlignmentAdapter",
+    "BaseAdapter",
+    "DistanceAdapter",
+    "DistanceRequest",
+    "IndexPlan",
+    "IndexRequest",
+    "ParseContext",
+    "PlanContext",
+    "request_molecule",
+]

gseek/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Built-in adapters.
+
+Concrete modules land per the milestone plan:
+
+- M1: :mod:`gseek.adapters.blast`, :mod:`gseek.adapters.minimap2`
+- M2: :mod:`gseek.adapters.kma`, :mod:`gseek.adapters.mummer`
+- M3: :mod:`gseek.adapters.bwa`, :mod:`gseek.adapters.mash`,
+  :mod:`gseek.adapters.sourmash`
+- M4: protein BLAST modes, sourmash gather, :mod:`gseek.adapters.skani`
+
+Each module exposes a class named ``ADAPTER``; add its dotted module path to
+:data:`gseek.registry.BUILTIN_MODULES` when it is ready.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []