seqforge 2026.7.1__py3-none-any.whl

seqforge/cli/processing.py

@@ -0,0 +1,192 @@
+"""`seqforge processing` -- the PROCESSING manifest: what to DO with a dataset. Many per dataset."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+import yaml
+from pydantic import ValidationError
+
+from .. import __version__
+from ..kb import load_spec
+from ..manifest import (
+    Instruction,
+    PolicyError,
+    ProcessingInputs,
+    exit_code_for_report,
+    fill_processing,
+    instructions_from_assertions,
+    prep_type_from_assertions,
+    processing_content_hash,
+    validate_processing,
+)
+from ..models.assertion import Assertion
+from ._common import _load_manifest, _load_processing, _parse_quantify
+from .root import processing_app
+
+
+def _instructions_from(path: Path | None) -> list[Instruction]:
+    """Rebuild the instructable surface from `harvest extract`'s artifact.
+
+    The precedence ladder (§7) is flag > instruction > policy, and `resolve_processing` has always
+    implemented it — its `PolicyError` even tells you to "name an assembly in an --instruction
+    document". That branch was unreachable: `--assembly` was a REQUIRED option, and nothing passed
+    `instructions=` from any production caller. This is the last mile of a join that already existed.
+
+    Note what is NOT happening: the model does not decide anything here. It found a claim in prose and
+    code verified the quote greps back and entails the value; this reads that record and applies
+    precedence. "We can accept instructions because we never trust the model to act on them, only to
+    find them."
+    """
+    if path is None:
+        return []
+    payload = json.loads(path.read_text())
+    if isinstance(payload, list):
+        raise ValueError(
+            "this looks like a pre-2026.7 assertions.json (a bare list). It cannot say which "
+            "documents were --instruction, and only those may set processing.*. Re-run "
+            "`seqforge harvest extract`."
+        )
+    docs = frozenset(payload.get("instruction_docs", ()))
+    parsed = [Assertion.model_validate(a) for a in payload.get("assertions", ())]
+    instructions, conflicts = instructions_from_assertions(parsed, instruction_docs=docs)
+    if conflicts:
+        raise ValueError(
+            f"{len(conflicts)} instruction(s) disagree with each other; only their author can "
+            f"settle that: " + "; ".join(c.field for c in conflicts)
+        )
+    return instructions
+
+
+def _prep_type_from(path: Path | None) -> str | None:
+    """The cells-vs-nuclei prep from `harvest extract`'s artifact, normalized. `None` if absent.
+
+    A span-verified biology fact (``library.prep_type``) that code — not the model — maps to the
+    primary soloFeature: a single-nucleus prep promotes GeneFull. The model named the biology and
+    verified its quote; this reads that record. See :func:`resolve_features`.
+    """
+    if path is None:
+        return None
+    payload = json.loads(path.read_text())
+    if isinstance(payload, list):  # a pre-2026.7 bare list; `_instructions_from` already refuses it
+        return None
+    parsed = [Assertion.model_validate(a) for a in payload.get("assertions", ())]
+    return prep_type_from_assertions(parsed)
+
+
+@processing_app.command("new")
+def processing_new(
+    dataset_path: Path = typer.Argument(..., help="Path to the dataset manifest.yaml."),
+    assembly: str | None = typer.Option(
+        None, "--assembly", help="liulab-genome UCSC assembly id (e.g. ce11)."
+    ),
+    annotation: str | None = typer.Option(
+        None, "--annotation", help="Registered GTF name (e.g. WS298)."
+    ),
+    assertions: Path | None = typer.Option(
+        None,
+        "--assertions",
+        help="Span-verified assertions from `harvest extract` (seqforge/assertions.json). "
+        "Instructions in them fill what no flag supplied.",
+    ),
+    quantify: str | None = typer.Option(
+        None,
+        "--quantify",
+        help="Comma-separated soloFeatures. EXACT replacement of the default (which counts all five).",
+    ),
+    threads: int | None = typer.Option(None, "--threads", help="Threads per mapping job."),
+    processing_id: str = typer.Option("default", "--id", help="Human slug for this recipe."),
+    pin: bool = typer.Option(
+        True,
+        "--pin/--template",
+        help="Bind to this dataset's hash, or leave it portable across datasets.",
+    ),
+    out: Path | None = typer.Option(None, "-o", "--out", help="Write here (default: stdout)."),
+) -> None:
+    """Author a PROCESSING manifest: what to DO with a dataset. Many per dataset.
+
+    With no flags you get the policy default, which counts every soloFeature — so the common
+    case needs no decision from you. --quantify replaces that list exactly; narrowing it warns,
+    because dropping a feature is the only irreversible act here.
+    """
+    dataset = _load_manifest(dataset_path)
+    spec = load_spec(dataset.library.chemistry.value[0])
+    try:
+        instructions = _instructions_from(assertions)
+        prep_type = _prep_type_from(assertions)
+    except (OSError, ValueError, ValidationError) as exc:
+        typer.echo(f"{assertions}: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    try:
+        processing, warnings = fill_processing(
+            spec=spec,
+            dataset=dataset,
+            processing=ProcessingInputs(
+                assembly=assembly,
+                annotation_name=annotation,
+                features=_parse_quantify(quantify),
+                threads=threads,
+            ),
+            instructions=instructions,
+            prep_type=prep_type,
+            processing_id=processing_id,
+            pin=pin,
+            seqforge_version=__version__,
+        )
+    except (PolicyError, ValidationError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2) from exc
+    report = validate_processing(processing, dataset=dataset)
+    payload = yaml.safe_dump(processing.model_dump(mode="json"), sort_keys=True)
+    if out is not None:
+        out.write_text(payload)
+        typer.echo(
+            json.dumps(
+                {
+                    "processing": str(out),
+                    "report": report.model_dump(mode="json"),
+                    "warnings": [w.model_dump(mode="json") for w in warnings],
+                },
+                indent=2,
+            )
+        )
+    else:
+        typer.echo(payload)
+    raise typer.Exit(exit_code_for_report(report))
+
+
+@processing_app.command("validate")
+def processing_validate(
+    processing_path: Path = typer.Argument(..., help="Path to a processing.yaml."),
+    dataset_path: Path | None = typer.Option(
+        None, "--dataset", help="Cross-check against this dataset manifest (pin + organism)."
+    ),
+) -> None:
+    """Validate a processing manifest. Exit 3 on a Blocker."""
+    processing = _load_processing(processing_path)
+    dataset = _load_manifest(dataset_path) if dataset_path is not None else None
+    report = validate_processing(processing, dataset=dataset)
+    typer.echo(json.dumps(report.model_dump(mode="json"), indent=2))
+    raise typer.Exit(exit_code_for_report(report))
+
+
+@processing_app.command("hash")
+def processing_hash_cmd(
+    processing_path: Path = typer.Argument(..., help="Path to a processing.yaml."),
+) -> None:
+    """Print the processing manifest's content hash and whether it matches the recorded one."""
+    processing = _load_processing(processing_path)
+    content = processing_content_hash(processing)
+    typer.echo(
+        json.dumps(
+            {
+                "processing_hash": content,
+                "recorded_hash": processing.provenance.processing_hash,
+                "matches": content == processing.provenance.processing_hash,
+                "pinned_to": processing.dataset.dataset_hash if processing.dataset else None,
+            },
+            indent=2,
+        )
+    )

seqforge/cli/project.py

@@ -0,0 +1,52 @@
+"""`seqforge project` -- project-level views over a multi-assay compile (sample_metadata + index)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from ._common import _load_manifest
+from .root import project_app
+
+
+@project_app.command("metadata")
+def project_metadata(
+    workspace: Path = typer.Option(Path("."), "-C", "--workspace", help="Root holding seqforge/."),
+) -> None:
+    """Regenerate seqforge/sample_metadata.tsv + project.yaml from the per-assay manifest(s).
+
+    Reads whatever manifests are already under seqforge/ — a single top-level manifest.yaml, or one
+    per assay subdir — and unions their samples into the flat one-row-per-sample table + the assay
+    index. Deterministic: same manifests in, same files out. `run` writes these automatically; this
+    verb rebuilds them (after editing a manifest, say) without recompiling.
+    """
+    from ..project import discover_assays, write_project_views
+
+    assays = discover_assays(workspace)
+    if not assays:
+        typer.echo(json.dumps({"error": "no manifest.yaml found under seqforge/"}), err=True)
+        raise typer.Exit(3)
+    infos: list[dict[str, object]] = []
+    for subdir, manifest_path in assays:
+        manifest = _load_manifest(manifest_path)
+        infos.append(
+            {
+                "chemistry": manifest.library.chemistry.value[0],
+                "subdir": subdir,
+                "n_samples": len(manifest.experiment.samples),
+                "manifest": str(manifest_path),
+            }
+        )
+    tsv_path, project_path = write_project_views(workspace, infos)
+    typer.echo(
+        json.dumps(
+            {
+                "sample_metadata": str(tsv_path),
+                "project": str(project_path),
+                "n_assays": len(infos),
+            },
+            indent=2,
+        )
+    )

seqforge/cli/resolve.py

@@ -0,0 +1,55 @@
+"""`seqforge resolve` -- score FASTQ bytes + KB into a ranked, escalated chemistry decision."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from ..resolve import Hypothesis, resolve_dataset
+from ._common import _auto_cpus
+from .root import resolve_app
+
+
+@resolve_app.command("score")
+def resolve_score(
+    files: list[Path] = typer.Argument(..., help="The dataset's FASTQ .gz files."),
+    workspace: Path = typer.Option(
+        Path("."), "-C", "--workspace", help="Root for seqforge/ state."
+    ),
+    assert_chemistry: str | None = typer.Option(
+        None,
+        "--assert-chemistry",
+        help="A metadata-asserted chemistry (the span-verified hypothesis).",
+    ),
+    explain: bool = typer.Option(
+        False, "--explain", help="Also emit the JSON-safe evidence matrices."
+    ),
+    no_cache: bool = typer.Option(
+        False, "--no-cache", help="Do not read/write seqforge/ artifacts."
+    ),
+    max_reads: int = typer.Option(200_000, help="Bounded read budget."),
+    max_bytes: int = typer.Option(256 * 1024 * 1024, help="Bounded decompressed-byte cap."),
+    cpus: int = typer.Option(
+        0, "--cpus", help="Parallel probe workers. 0 = auto (min(8, CPUs)); 1 = sequential."
+    ),
+) -> None:
+    """Score FASTQ bytes + KB into a ResolveResult. Exit 3 on a Blocker, 4 on an open Conflict/question."""
+    hypothesis = Hypothesis(value=assert_chemistry) if assert_chemistry else None
+    output = resolve_dataset(
+        [str(f) for f in files],
+        hypothesis=hypothesis,
+        workspace=workspace,
+        max_reads=max_reads,
+        max_bytes=max_bytes,
+        use_cache=not no_cache,
+        cpus=_auto_cpus(cpus),
+    )
+    payload: dict[str, object] = output.result.model_dump(mode="json")
+    if explain:
+        payload = {"result": payload, "matrices": output.matrices}
+    typer.echo(json.dumps(payload, indent=2))
+    code = output.exit_code()
+    if code != 0:
+        raise typer.Exit(code)

seqforge/cli/root.py

@@ -0,0 +1,66 @@
+"""The root Typer app and every command group's sub-Typer, wired together.
+
+Defined in one place so a command module can import exactly the group it registers onto without
+pulling in its siblings. The ``add_typer`` wiring here fixes the CLI's shape; the verbs attach when
+each command module is imported (see this package's ``__init__``). Introspected by
+``test_skills.py`` -- a renamed verb goes red there, not here.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import __version__
+
+app = typer.Typer(
+    name="seqforge",
+    help="Compile FASTQ + metadata into a validated library manifest and a Snakemake config.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+schema_app = typer.Typer(help="Export JSON Schema from the Pydantic models (the source of truth).")
+app.add_typer(schema_app, name="schema")
+
+kb_app = typer.Typer(help="The executable, self-testing knowledge base.")
+app.add_typer(kb_app, name="kb")
+
+io_app = typer.Typer(help="The network + onlist surface (pooch-cached, sha256-verified).")
+app.add_typer(io_app, name="io")
+
+onlist_app = typer.Typer(help="Barcode-whitelist (onlist) registry.")
+io_app.add_typer(onlist_app, name="onlist")
+
+resolve_app = typer.Typer(help="Score bytes + KB into a ranked, escalated chemistry decision.")
+app.add_typer(resolve_app, name="resolve")
+
+manifest_app = typer.Typer(
+    help="The DATASET manifest: what the data IS. Immutable, one per dataset."
+)
+app.add_typer(manifest_app, name="manifest")
+processing_app = typer.Typer(
+    help="The PROCESSING manifest: what to DO with a dataset. Many per dataset."
+)
+app.add_typer(processing_app, name="processing")
+
+harvest_app = typer.Typer(
+    help="Prose/metadata -> span-verified Assertions (the one LLM touchpoint)."
+)
+app.add_typer(harvest_app, name="harvest")
+
+eval_app = typer.Typer(help="The evals harness: measure what unit tests cannot (brief §9).")
+app.add_typer(eval_app, name="eval")
+
+hook_app = typer.Typer(help="Agent hooks: the rules as mechanism, not aspiration (design §4.2).")
+app.add_typer(hook_app, name="hook")
+
+project_app = typer.Typer(
+    help="Project-level views over a multi-assay compile (sample_metadata.tsv + project.yaml)."
+)
+app.add_typer(project_app, name="project")
+
+
+@app.command()
+def version() -> None:
+    """Print the seqforge version."""
+    typer.echo(__version__)