seqforge 2026.7.1__py3-none-any.whl

seqforge/__init__.py

@@ -0,0 +1,16 @@
+"""seqforge — compile FASTQ + metadata into a validated library manifest and a Snakemake config.
+
+A compiler, not a chatbot: deterministic code owns every decision; the LLM only parses prose into
+span-verified assertions and arbitrates already-flagged ambiguity. See ``docs/design.md``.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - version is provided by the installed package metadata
+    from importlib.metadata import version
+
+    __version__ = version("seqforge")
+except Exception:  # pragma: no cover - not installed; mirror the static CalVer in pyproject.toml
+    __version__ = "2026.7.1"
+
+__all__ = ["__version__"]

seqforge/cli/__init__.py

@@ -0,0 +1,38 @@
+"""The ``seqforge`` Typer application, assembled from one module per command group.
+
+The CLI is the API: every skill action maps to a deterministic ``seqforge <verb>`` (JSON on stdout by
+default) that runs with no LLM in the loop -- only ``harvest extract`` and the opt-in
+``resolve adjudicate`` touch an LLM. Exit codes are uniform: ``0`` OK, ``1`` ERROR, ``2`` USAGE,
+``3`` BLOCKED (a Blocker), ``4`` NEEDS_HUMAN (an open Conflict / question).
+
+Importing this package builds ``app``: :mod:`.root` defines the shared Typer instances, and importing
+each command module registers its verbs onto them. A handful of internals are re-exported because the
+test suite and ``seqforge run`` reach for them by name.
+"""
+
+from __future__ import annotations
+
+# Importing each command module runs its @command decorators, registering the verbs onto `app`.
+# The imports look unused; the registration is the side effect that assembles the CLI.
+from . import (  # noqa: F401
+    compose,
+    eval,
+    harvest,
+    hook,
+    io,
+    kb,
+    manifest,
+    probe,
+    processing,
+    project,
+    resolve,
+    run,
+    schema,
+)
+from ._common import _emit, _StageOut  # noqa: F401
+from .harvest import _harvest_extract_pipeline  # noqa: F401
+from .manifest import _fill_manifest_pipeline  # noqa: F401
+from .root import app
+from .run import _harvest_halts_run  # noqa: F401
+
+__all__ = ["app"]

seqforge/cli/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m seqforge.cli`` -- the entry point the generated hook shim invokes."""
+
+from __future__ import annotations
+
+from . import app
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

seqforge/cli/_common.py

@@ -0,0 +1,105 @@
+"""Shared CLI helpers used across command groups: stage results, safe loaders, small parsers.
+
+None of these touch a Typer app -- they are the plumbing every command group reuses. `_StageOut`
+decouples *what a stage says and whether it refused* (the exit code) from *where that output goes*,
+which is what lets one stage body serve both a standalone verb and the one-pass `run`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+import yaml
+from pydantic import ValidationError
+
+from ..io.taxonomy import resolve as resolve_organism
+from ..models.dataset import DatasetManifest
+from ..models.processing import ProcessingManifest
+
+
+def _today() -> str:
+    """Today, for the ``fetched`` stamp on a generated vocabulary file.
+
+    Local import and a function rather than a module constant: a constant would be evaluated at import
+    time, and every artifact seqforge writes is content-addressed — a clock reachable from module
+    scope is a clock that eventually ends up inside a hash.
+    """
+    import datetime
+
+    return datetime.date.today().isoformat()
+
+
+@dataclass(frozen=True)
+class _StageOut:
+    """One stage's result, decoupled from how it is printed.
+
+    A stage decides *what* to say and *whether it is a refusal* (the exit code); the command wrapper
+    decides *where* it goes. That split is what lets a single stage body serve both a standalone verb
+    (which echoes it and exits) and ``seqforge run`` (which folds it into one summary). ``payload`` is
+    a dict rendered as JSON, or a bare string echoed as-is — ``FillError`` prints a plain sentence,
+    ``records_unavailable`` prints JSON, and both must keep doing exactly that.
+    """
+
+    payload: dict[str, object] | str
+    code: int
+    err: bool = False
+
+
+def _emit(out: _StageOut) -> None:
+    """Print a stage result the way a standalone verb does, then exit with its code."""
+    body = out.payload if isinstance(out.payload, str) else json.dumps(out.payload, indent=2)
+    typer.echo(body, err=out.err)
+    raise typer.Exit(out.code)
+
+
+def _auto_cpus(cpus: int) -> int:
+    """Resolve ``--cpus``: a positive value is taken as-is; ``0`` means auto = ``min(8, detected)``.
+
+    Files probe in parallel across processes, and cores are not a budget — this only decides how
+    fast, never what. ``0`` is the default so the common multicore case is fast without a flag, while a
+    shared login node can be pinned with ``--cpus 1``. The cap at 8 keeps a 96-core node from
+    fork-bombing itself on a 12-file dataset where the win is already gone by 8.
+    """
+    if cpus > 0:
+        return cpus
+    import os
+
+    return max(1, min(8, os.cpu_count() or 1))
+
+
+def _load_manifest(path: Path) -> DatasetManifest:
+    try:
+        return DatasetManifest.model_validate(yaml.safe_load(path.read_text()))
+    except (OSError, ValidationError, ValueError) as exc:
+        typer.echo(f"cannot read manifest {path}: {exc}", err=True)
+        raise typer.Exit(2) from exc
+
+
+def _load_processing(path: Path) -> ProcessingManifest:
+    try:
+        return ProcessingManifest.model_validate(yaml.safe_load(path.read_text()))
+    except (OSError, ValidationError, ValueError) as exc:
+        typer.echo(f"cannot read processing manifest {path}: {exc}", err=True)
+        raise typer.Exit(2) from exc
+
+
+def _resolve_organism(value: str, *, offline: bool = False) -> int:
+    """`--organism` takes a taxid or a name. A bare integer is taken at face value.
+
+    Not "is it all digits, else look it up" with a fallback -- a name that happens to be numeric is
+    not a thing, and a taxid that fails to parse should say so rather than be searched for on NCBI.
+    """
+    text = value.strip()
+    if text.isdigit():
+        return int(text)
+    return resolve_organism(text, offline=offline)
+
+
+def _parse_quantify(value: str | None) -> tuple[str, ...] | None:
+    """`--quantify Gene,GeneFull` -> the tuple. The MODEL validates membership, not this parser."""
+    if value is None:
+        return None
+    return tuple(v.strip() for v in value.split(",") if v.strip())

seqforge/cli/compose.py

@@ -0,0 +1,119 @@
+"""`seqforge compose` -- compile (dataset, processing) -> Snakefile + config.yaml + units.tsv."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from .. import __version__
+from ..compose import ComposeError, compose
+from ..io import default_registry
+from ..kb import load_spec
+from ..manifest import (
+    ProcessingInputs,
+    exit_code_for_report,
+    fill_processing,
+    validate_manifest,
+    validate_processing,
+)
+from ._common import _load_manifest, _load_processing
+from .root import app
+
+
+@app.command("compose")
+def compose_cmd(
+    manifest_path: Path = typer.Argument(..., help="Path to a validated manifest.yaml."),
+    processing_path: Path | None = typer.Option(
+        None, "--processing", help="A processing manifest. Omit to use policy defaults."
+    ),
+    assembly: str | None = typer.Option(
+        None, "--assembly", help="Genome, when composing without --processing."
+    ),
+    annotation: str | None = typer.Option(
+        None, "--annotation", help="Registered GTF name, when composing without --processing."
+    ),
+    workspace: Path = typer.Option(
+        Path("."), "-C", "--workspace", help="Root for seqforge/ state."
+    ),
+    outdir: str = typer.Option(
+        "results", help="Pipeline output directory (written into the config)."
+    ),
+    fastq_dir: Path | None = typer.Option(
+        None,
+        "--fastq-dir",
+        help="Where this machine keeps the FASTQs. Without it units.tsv carries bare basenames "
+        "and the pipeline cannot find its input.",
+    ),
+    onlist_dir: Path | None = typer.Option(
+        None,
+        "--onlist-dir",
+        help="Directory of downloaded barcode whitelists (<name>.txt.gz). Checked before the "
+        "network, so a compute node with no internet still composes. Env: SEQFORGE_ONLIST_DIR.",
+    ),
+    sif_dir: Path | None = typer.Option(
+        None,
+        "--sif-dir",
+        envvar="LIU_LAB_PACKAGES",
+        help="Directory of prebuilt liulab-runtime images (liulab-runtime_<env>.sif). Used instead "
+        "of the ghcr tag when the file is there, for nodes that cannot reach ghcr.io.",
+    ),
+) -> None:
+    """Compile (dataset, processing) -> Snakefile + config.yaml + units.tsv.
+
+    ``--processing`` is optional: a processing manifest exists because someone wanted something
+    non-default, and requiring one per dataset would mean 10^4 boilerplate files nobody reads. Either
+    way compose writes the fully-resolved, dataset-bound manifest it used to processing.lock.yaml, so
+    the run's state is on disk regardless. Exit 3 if a gate fails.
+    """
+    manifest = _load_manifest(manifest_path)
+    report = validate_manifest(manifest)
+    if not report.ok:
+        typer.echo(json.dumps(report.model_dump(mode="json"), indent=2), err=True)
+        typer.echo("refusing to compose an invalid manifest", err=True)
+        raise typer.Exit(exit_code_for_report(report))
+
+    if processing_path is not None:
+        processing = _load_processing(processing_path)
+    else:
+        if assembly is None or annotation is None:
+            # The one thing with no safe default. Deriving an assembly from experiment.organism would
+            # mean choosing hg38 vs hg19 vs T2T on the user's behalf — a policy call, and that map is
+            # liulab-genome's job. Refuse, but make the refusal actionable.
+            typer.echo(
+                f"compose needs a genome: this dataset's organism is taxid "
+                f"{manifest.experiment.organism.value}. Pass --assembly/--annotation, or author one "
+                f"with `seqforge processing new`.",
+                err=True,
+            )
+            raise typer.Exit(2)
+        processing, _ = fill_processing(
+            spec=load_spec(manifest.library.chemistry.value[0]),
+            dataset=manifest,
+            processing=ProcessingInputs(assembly=assembly, annotation_name=annotation),
+            seqforge_version=__version__,
+        )
+
+    p_report = validate_processing(processing, dataset=manifest)
+    if not p_report.ok:
+        typer.echo(json.dumps(p_report.model_dump(mode="json"), indent=2), err=True)
+        typer.echo("refusing to compose with an invalid processing manifest", err=True)
+        raise typer.Exit(exit_code_for_report(p_report))
+
+    try:
+        result = compose(
+            manifest,
+            processing,
+            registry=default_registry(offline=False, local_dir=onlist_dir),
+            workspace=workspace,
+            outdir=outdir,
+            fastq_dir=fastq_dir,
+            sif_dir=sif_dir,
+        )
+    except ComposeError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(3) from exc
+    typer.echo(json.dumps(result.model_dump(mode="json"), indent=2))
+    if any(v == "fail" for v in result.gate.values()):
+        raise typer.Exit(3)

seqforge/cli/eval.py

@@ -0,0 +1,103 @@
+"""`seqforge eval` -- the evals harness: measure what unit tests cannot (design/brief S9)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from .root import eval_app
+
+
+@eval_app.command("list")
+def eval_list(
+    cases_dir: Path | None = typer.Option(
+        None, "--cases", help="Case root (default: evals/cases)."
+    ),
+) -> None:
+    """List the eval corpus: id, expected outcome, and whether the case needs an LLM."""
+    from ..evals import CaseError, load_cases
+
+    try:
+        cases = load_cases(cases_dir)
+    except CaseError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2) from exc
+    payload = [
+        {
+            "id": c.id,
+            "outcome": c.expected.outcome,
+            "needs_llm": c.has_prose and c.recipe.hypothesis is None,
+            "description": " ".join(c.expected.description.split())[:100],
+        }
+        for c in cases
+    ]
+    typer.echo(json.dumps(payload, indent=2))
+
+
+@eval_app.command("run")
+def eval_run(
+    case: list[str] = typer.Option(None, "--case", help="Run only these case ids (repeatable)."),
+    cases_dir: Path | None = typer.Option(
+        None, "--cases", help="Case root (default: evals/cases)."
+    ),
+    llm: bool = typer.Option(
+        False, "--llm/--no-llm", help="Run prose cases through harvest extract (costs tokens)."
+    ),
+    provider: str | None = typer.Option(
+        None, "--provider", help="anthropic | deepseek | openai-compatible (default: auto-detect)."
+    ),
+    model: str | None = typer.Option(
+        None, "--model", help="Override the provider's default model."
+    ),
+    trials: int = typer.Option(
+        1, "--trials", min=1, help="Re-run each prose case N times; extraction is nondeterministic."
+    ),
+    fail_under: float = typer.Option(
+        1.0, "--fail-under", help="Exit 3 if field accuracy drops below this."
+    ),
+) -> None:
+    """Run the eval corpus and report brief §9's metrics.
+
+    `--no-llm` (the default) restricts to deterministic cases, so this runs in a CI with no API key;
+    prose cases skip rather than fail. Exit 3 if any false-accept occurs or accuracy drops below
+    `--fail-under` — a false accept is never tolerable at any threshold, so it is not on a slider.
+    """
+    from ..evals import CaseError, Grade, load_cases, run_cases
+    from ..harvest import ProviderUnavailable, resolve_provider
+
+    try:
+        cases = load_cases(cases_dir, only=list(case) if case else None)
+    except CaseError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2) from exc
+    if not cases:
+        typer.echo("no cases found", err=True)
+        raise typer.Exit(2)
+
+    llm_provider = None
+    if llm:
+        try:
+            llm_provider = resolve_provider(provider)
+        except ProviderUnavailable as exc:
+            typer.echo(json.dumps({"error": "no_provider", "detail": str(exc)}, indent=2), err=True)
+            raise typer.Exit(1) from exc
+
+    report, runs = run_cases(cases, llm=llm, provider=llm_provider, model=model, trials=trials)
+    typer.echo(json.dumps(report.model_dump(mode="json"), indent=2))
+
+    false_accepts = [r for r in runs if r.skipped is None and r.grade.grade is Grade.FALSE_ACCEPT]
+    if false_accepts:
+        typer.echo(
+            f"FALSE ACCEPT in {len(false_accepts)} case(s): "
+            f"{[r.case_id for r in false_accepts]} — a confident wrong manifest is the one "
+            f"failure the corpus never recovers from",
+            err=True,
+        )
+        raise typer.Exit(3)
+    if report.field_accuracy < fail_under:
+        typer.echo(
+            f"field accuracy {report.field_accuracy:.3f} < --fail-under {fail_under}", err=True
+        )
+        raise typer.Exit(3)