dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/molbio/__init__.py

@@ -0,0 +1,101 @@
+"""Deterministic molecular-biology simulation and rule-design APIs."""
+
+from .assembly import AssemblyFragment, simulate_assembly
+from .crispr import scan_crispr_candidates
+from .optimization import (
+    CodonUsageTable,
+    RuleOptimizationConfig,
+    generate_mutation_library,
+    optimize_codons,
+    optimize_protein_codons,
+    optimize_sequence_rules,
+)
+from .primer3_design import Primer3CLIDesignAdapter
+from .primers import match_primer, prepare_primer_design, primer_properties, simulate_pcr
+from .restriction import (
+    LigationFragment,
+    as_ligation_fragment,
+    check_end_compatibility,
+    classify_restriction_end,
+    digest_restriction,
+    ligate_fragments,
+)
+from .results import (
+    Amplicon,
+    AssemblyResult,
+    AssemblyStep,
+    CodonOptimizationResult,
+    ConditionalAnalysis,
+    CrisprScanResult,
+    DigestCut,
+    DigestFragment,
+    EndDescriptor,
+    EndTypeResult,
+    LigationCompatibilityResult,
+    LigationResult,
+    MolBioResult,
+    Mutation,
+    MutationLibraryResult,
+    OffTargetHit,
+    PCRResult,
+    PrimerBindingHit,
+    PrimerDesignCandidate,
+    PrimerDesignInterfaceResult,
+    PrimerDesignRequest,
+    PrimerMatchResult,
+    PrimerPropertiesResult,
+    RestrictionDigestResult,
+    RuleOptimizationResult,
+    SequenceChange,
+    SequenceVariant,
+)
+
+__all__ = [
+    "Amplicon",
+    "AssemblyFragment",
+    "AssemblyResult",
+    "AssemblyStep",
+    "CodonOptimizationResult",
+    "CodonUsageTable",
+    "ConditionalAnalysis",
+    "CrisprScanResult",
+    "DigestCut",
+    "DigestFragment",
+    "EndDescriptor",
+    "EndTypeResult",
+    "LigationCompatibilityResult",
+    "LigationFragment",
+    "LigationResult",
+    "MolBioResult",
+    "Mutation",
+    "MutationLibraryResult",
+    "OffTargetHit",
+    "PCRResult",
+    "Primer3CLIDesignAdapter",
+    "PrimerBindingHit",
+    "PrimerDesignCandidate",
+    "PrimerDesignInterfaceResult",
+    "PrimerDesignRequest",
+    "PrimerMatchResult",
+    "PrimerPropertiesResult",
+    "RestrictionDigestResult",
+    "RuleOptimizationConfig",
+    "RuleOptimizationResult",
+    "SequenceChange",
+    "SequenceVariant",
+    "as_ligation_fragment",
+    "check_end_compatibility",
+    "classify_restriction_end",
+    "digest_restriction",
+    "generate_mutation_library",
+    "ligate_fragments",
+    "match_primer",
+    "optimize_codons",
+    "optimize_protein_codons",
+    "optimize_sequence_rules",
+    "prepare_primer_design",
+    "primer_properties",
+    "scan_crispr_candidates",
+    "simulate_assembly",
+    "simulate_pcr",
+]

dnakit/molbio/_shared.py

@@ -0,0 +1,266 @@
+"""Shared validation and audit helpers for molecular-biology simulations."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Mapping
+from typing import TypeVar
+
+from dnakit.core import (
+    DNA,
+    DNASequence,
+    ExecutionMode,
+    ImplementationInfo,
+    ImplementationLabel,
+    Issue,
+    OriginClass,
+    Provenance,
+    ReferenceInfo,
+    Topology,
+)
+from dnakit.core._json import FrozenDict, freeze_mapping
+from dnakit.core.facade import resolve_single_dna
+from dnakit.exceptions import ConfigurationError, InvalidAlphabetError, UnsupportedGapOperationError
+
+_IUPAC = frozenset("ACGTRYSWKMBDHVN")
+_CANONICAL = frozenset("ACGT")
+T = TypeVar("T")
+_COMPLEMENT = str.maketrans(
+    {
+        "A": "T",
+        "C": "G",
+        "G": "C",
+        "T": "A",
+        "R": "Y",
+        "Y": "R",
+        "S": "S",
+        "W": "W",
+        "K": "M",
+        "M": "K",
+        "B": "V",
+        "D": "H",
+        "H": "D",
+        "V": "B",
+        "N": "N",
+    }
+)
+
+IUPAC_BASES: Mapping[str, frozenset[str]] = {
+    "A": frozenset("A"),
+    "C": frozenset("C"),
+    "G": frozenset("G"),
+    "T": frozenset("T"),
+    "R": frozenset("AG"),
+    "Y": frozenset("CT"),
+    "S": frozenset("CG"),
+    "W": frozenset("AT"),
+    "K": frozenset("GT"),
+    "M": frozenset("AC"),
+    "B": frozenset("CGT"),
+    "D": frozenset("AGT"),
+    "H": frozenset("ACT"),
+    "V": frozenset("ACG"),
+    "N": frozenset("ACGT"),
+}
+
+
+def validate_positive_int(value: object, name: str, *, maximum: int | None = None) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ConfigurationError(f"{name} must be a positive integer.", context={name: value})
+    if maximum is not None and value > maximum:
+        raise ConfigurationError(
+            f"{name} exceeds its supported maximum.",
+            context={name: value, "maximum": maximum},
+        )
+    return value
+
+
+def validate_non_negative_int(value: object, name: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise ConfigurationError(f"{name} must be a non-negative integer.", context={name: value})
+    return value
+
+
+def finite_fraction(value: object, name: str) -> float:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or not 0.0 <= value <= 1.0
+    ):
+        raise ConfigurationError(f"{name} must be finite and between 0 and 1.")
+    return float(value)
+
+
+def validate_text(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigurationError(f"{name} must be a non-empty string.")
+    return value
+
+
+def materialize_bounded(
+    values: Iterable[T],
+    *,
+    max_items: int,
+    name: str,
+    reject_text: bool = True,
+) -> tuple[T, ...]:
+    """Materialize a finite iterable under an explicit item limit."""
+
+    validate_positive_int(max_items, f"max_{name}", maximum=100_000_000)
+    if reject_text and isinstance(values, (str, bytes)):
+        raise ConfigurationError(f"{name} must be a non-text iterable.")
+    resolved: list[T] = []
+    for item in values:
+        if len(resolved) >= max_items:
+            raise ConfigurationError(f"{name} exceeds its configured item limit.")
+        resolved.append(item)
+    return tuple(resolved)
+
+
+def validate_iupac_text(value: object, name: str, *, allow_empty: bool = False) -> str:
+    if not isinstance(value, str):
+        raise ConfigurationError(f"{name} must be a DNA string.")
+    resolved = value.upper()
+    if not resolved and not allow_empty:
+        raise ConfigurationError(f"{name} must be non-empty.")
+    invalid = sorted(set(resolved) - _IUPAC)
+    if invalid:
+        raise InvalidAlphabetError(
+            f"{name} contains symbols outside the DNA IUPAC alphabet.",
+            context={"invalid_symbols": invalid},
+        )
+    return resolved
+
+
+def require_sequence(
+    sequence: DNA | DNASequence,
+    *,
+    operation: str,
+    max_length: int,
+    canonical: bool = False,
+    allow_circular: bool = True,
+    allow_empty: bool = False,
+) -> str:
+    if isinstance(sequence, DNA):
+        sequence, _ = resolve_single_dna(sequence)
+    if not isinstance(sequence, DNASequence):
+        raise ConfigurationError(
+            f"{operation} requires a DNASequence.",
+            context={"input_type": type(sequence).__name__},
+        )
+    validate_positive_int(max_length, "max_length", maximum=100_000_000)
+    if sequence.is_gapped:
+        raise UnsupportedGapOperationError(
+            f"{operation} cannot silently omit explicit Gap objects.",
+            code="UNSUPPORTED_GAPPED_MOLBIO_OPERATION",
+        )
+    if not allow_circular and sequence.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            f"{operation} requires linear topology.",
+            code="CIRCULAR_MOLBIO_OPERATION_UNSUPPORTED",
+        )
+    symbols = sequence.symbols
+    if not symbols and not allow_empty:
+        raise ConfigurationError(f"{operation} requires a non-empty sequence.")
+    if len(symbols) > max_length:
+        raise ConfigurationError(
+            f"{operation} input exceeds max_length.",
+            code="MOLBIO_SEQUENCE_LIMIT_EXCEEDED",
+            context={"sequence_length": len(symbols), "max_length": max_length},
+        )
+    if canonical and set(symbols) - _CANONICAL:
+        raise InvalidAlphabetError(
+            f"{operation} requires canonical A/C/G/T symbols.",
+            code="AMBIGUOUS_MOLBIO_SEQUENCE_UNSUPPORTED",
+        )
+    return symbols
+
+
+def reverse_complement_text(value: str) -> str:
+    return value.translate(_COMPLEMENT)[::-1]
+
+
+def iupac_compatible(left: str, right: str) -> bool:
+    return bool(IUPAC_BASES[left] & IUPAC_BASES[right])
+
+
+def circular_slice(symbols: str, start: int, length: int) -> str:
+    if length < 0 or length > len(symbols):
+        raise ConfigurationError("Circular slice length must be within one template traversal.")
+    if not symbols:
+        return ""
+    start %= len(symbols)
+    return (symbols + symbols)[start : start + length]
+
+
+def native_provenance(
+    *,
+    reimplementation: bool = False,
+    reference_name: str | None = None,
+    reference_version: str | None = None,
+    reference_checksum: str | None = None,
+) -> Provenance:
+    return Provenance(
+        implementation=ImplementationInfo(
+            label=(
+                ImplementationLabel.REIMPLEMENTATION
+                if reimplementation
+                else ImplementationLabel.NATIVE
+            ),
+            execution_mode=ExecutionMode.INTERNAL,
+            origin_class=(
+                OriginClass.PUBLISHED_ALGORITHM if reimplementation else OriginClass.DNAKIT
+            ),
+        ),
+        reference=(
+            None
+            if reference_name is None
+            else ReferenceInfo(
+                reference_name,
+                version=reference_version,
+                checksum=reference_checksum,
+            )
+        ),
+    )
+
+
+def adapter_provenance(*, reference_name: str, reference_version: str | None = None) -> Provenance:
+    return Provenance(
+        implementation=ImplementationInfo(
+            label=ImplementationLabel.ADAPTER,
+            execution_mode=ExecutionMode.EXTERNAL,
+            origin_class=OriginClass.INTEGRATION,
+        ),
+        reference=ReferenceInfo(reference_name, version=reference_version),
+    )
+
+
+def freeze_parameters(values: Mapping[str, object]) -> FrozenDict:
+    return freeze_mapping(values)
+
+
+def validate_issues(issues: Iterable[Issue]) -> tuple[Issue, ...]:
+    resolved = tuple(issues)
+    if any(not isinstance(issue, Issue) for issue in resolved):
+        raise ConfigurationError("issues must contain only Issue objects.")
+    return resolved
+
+
+__all__ = [
+    "IUPAC_BASES",
+    "adapter_provenance",
+    "circular_slice",
+    "finite_fraction",
+    "freeze_parameters",
+    "iupac_compatible",
+    "materialize_bounded",
+    "native_provenance",
+    "require_sequence",
+    "reverse_complement_text",
+    "validate_issues",
+    "validate_iupac_text",
+    "validate_non_negative_int",
+    "validate_positive_int",
+    "validate_text",
+]

dnakit/molbio/assembly.py

@@ -0,0 +1,279 @@
+"""Deterministic ordered assembly simulations with explicit method boundaries."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from itertools import pairwise
+
+from dnakit.core import DNAAlphabet, DNASequence, Issue, IssueSeverity, Topology
+from dnakit.exceptions import ConfigurationError
+
+from ._shared import (
+    freeze_parameters,
+    materialize_bounded,
+    native_provenance,
+    require_sequence,
+    validate_positive_int,
+    validate_text,
+)
+from .restriction import LigationFragment, as_ligation_fragment, ligate_fragments
+from .results import AssemblyResult, AssemblyStep, DigestFragment
+
+
+@dataclass(frozen=True)
+class AssemblyFragment:
+    """Named linear fragment accepted by overlap-based assembly."""
+
+    id: str
+    sequence: DNASequence
+
+    def __post_init__(self) -> None:
+        validate_text(self.id, "assembly fragment id")
+        require_sequence(
+            self.sequence,
+            operation="assembly fragment construction",
+            max_length=100_000_000,
+            allow_circular=False,
+        )
+
+
+def _overlap_fragment(
+    value: DNASequence | AssemblyFragment | DigestFragment | LigationFragment,
+    index: int,
+) -> AssemblyFragment:
+    if isinstance(value, AssemblyFragment):
+        return value
+    if isinstance(value, DNASequence):
+        return AssemblyFragment(f"fragment_{index}", value)
+    if isinstance(value, (DigestFragment, LigationFragment)):
+        return AssemblyFragment(value.id, value.sequence)
+    raise ConfigurationError("Unsupported assembly fragment type.")
+
+
+def _longest_overlap(left: str, right: str, minimum: int, maximum: int) -> str:
+    upper = min(maximum, len(left), len(right))
+    for length in range(upper, minimum - 1, -1):
+        if left[-length:] == right[:length]:
+            return right[:length]
+    return ""
+
+
+def _resolve_overlap(
+    left: str,
+    right: str,
+    *,
+    explicit: str | None,
+    minimum: int,
+    maximum: int,
+) -> str:
+    if explicit is not None:
+        if not isinstance(explicit, str) or set(explicit) - set("ACGTRYSWKMBDHVN"):
+            raise ConfigurationError("Explicit overlaps must be uppercase DNA IUPAC strings.")
+        if not minimum <= len(explicit) <= maximum:
+            raise ConfigurationError("Explicit overlap length lies outside configured bounds.")
+        if not left.endswith(explicit) or not right.startswith(explicit):
+            raise ConfigurationError("Explicit overlap is not an exact suffix/prefix junction.")
+        return explicit
+    overlap = _longest_overlap(left, right, minimum, maximum)
+    if not overlap:
+        raise ConfigurationError(
+            "No exact overlap satisfies the configured assembly boundary.",
+            code="ASSEMBLY_OVERLAP_NOT_FOUND",
+        )
+    return overlap
+
+
+def simulate_assembly(
+    fragments: Iterable[DNASequence | AssemblyFragment | DigestFragment | LigationFragment],
+    *,
+    method: str,
+    overlaps: Iterable[str] | None = None,
+    min_overlap: int = 20,
+    max_overlap: int = 200,
+    circularize: bool = False,
+    allow_blunt: bool = False,
+    cycles: int = 1,
+    max_fragments: int = 1_000,
+    max_product_length: int = 100_000_000,
+) -> AssemblyResult:
+    """Simulate ordered Gibson/LCR overlaps or pre-digested GG/BioBrick ligation.
+
+    Golden Gate and BioBrick inputs must already carry validated end descriptors;
+    enzyme cutting, reaction kinetics, scar optimization, and cycle yield are not
+    inferred by this function.
+    """
+
+    normalized_method = method.lower() if isinstance(method, str) else ""
+    if normalized_method not in ("gibson", "lcr", "golden_gate", "biobrick"):
+        raise ConfigurationError("method must be gibson, lcr, golden_gate, or biobrick.")
+    validate_positive_int(max_fragments, "max_fragments", maximum=100_000)
+    validate_positive_int(max_product_length, "max_product_length", maximum=100_000_000)
+    validate_positive_int(cycles, "cycles", maximum=10_000)
+    if not isinstance(circularize, bool) or not isinstance(allow_blunt, bool):
+        raise ConfigurationError("Assembly boolean controls must be booleans.")
+    materialized: list[DNASequence | AssemblyFragment | DigestFragment | LigationFragment] = []
+    for item in fragments:
+        if len(materialized) >= max_fragments:
+            raise ConfigurationError("Assembly input exceeds max_fragments.")
+        materialized.append(item)
+    if len(materialized) < 2:
+        raise ConfigurationError("Assembly requires at least two fragments.")
+    issues = (
+        Issue(
+            "ASSEMBLY_KINETICS_NOT_MODELED",
+            IssueSeverity.INFO,
+            "The result is a deterministic sequence construction, not a reaction-yield model.",
+        ),
+    )
+    steps: list[AssemblyStep] = []
+    if normalized_method in ("golden_gate", "biobrick"):
+        ligation_inputs: list[LigationFragment] = []
+        for item in materialized:
+            if not isinstance(item, (DigestFragment, LigationFragment)):
+                raise ConfigurationError(
+                    "Golden Gate/BioBrick simulation requires pre-digested fragments with ends.",
+                    code="PREDIGESTED_ASSEMBLY_INPUT_REQUIRED",
+                )
+            ligation_inputs.append(as_ligation_fragment(item))
+        ligation = ligate_fragments(
+            ligation_inputs,
+            circularize=circularize,
+            allow_blunt=allow_blunt,
+            max_fragments=max_fragments,
+            max_product_length=max_product_length,
+        )
+        pairs = list(pairwise(ligation_inputs))
+        if circularize:
+            pairs.append((ligation_inputs[-1], ligation_inputs[0]))
+        for index, (left, right) in enumerate(pairs, 1):
+            steps.append(
+                AssemblyStep(
+                    index=index,
+                    left_fragment_id=left.id,
+                    right_fragment_id=right.id,
+                    operation="compatible_end_ligation",
+                    junction_sequence=left.right_end.overhang_sequence_5to3,
+                )
+            )
+        product = ligation.product
+    else:
+        validate_positive_int(min_overlap, "min_overlap", maximum=100_000)
+        validate_positive_int(max_overlap, "max_overlap", maximum=100_000)
+        if min_overlap > max_overlap:
+            raise ConfigurationError("min_overlap cannot exceed max_overlap.")
+        overlap_fragments = tuple(
+            _overlap_fragment(item, index) for index, item in enumerate(materialized, 1)
+        )
+        expected = len(overlap_fragments) if circularize else len(overlap_fragments) - 1
+        overlap_values = (
+            None
+            if overlaps is None
+            else materialize_bounded(
+                overlaps,
+                max_items=expected + 1,
+                name="assembly overlaps",
+            )
+        )
+        if overlap_values is not None and len(overlap_values) != expected:
+            raise ConfigurationError(
+                "overlaps must provide exactly one sequence per assembly junction."
+            )
+        if any(
+            fragment.sequence.strandedness is not overlap_fragments[0].sequence.strandedness
+            for fragment in overlap_fragments[1:]
+        ):
+            raise ConfigurationError("All assembly fragments must use the same strandedness.")
+        product_symbols = overlap_fragments[0].sequence.symbols
+        if len(product_symbols) > max_product_length:
+            raise ConfigurationError("Assembly product exceeds max_product_length.")
+        for index, (overlap_left, overlap_right) in enumerate(pairwise(overlap_fragments), 1):
+            overlap = _resolve_overlap(
+                overlap_left.sequence.symbols,
+                overlap_right.sequence.symbols,
+                explicit=None if overlap_values is None else overlap_values[index - 1],
+                minimum=min_overlap,
+                maximum=max_overlap,
+            )
+            addition = overlap_right.sequence.symbols[len(overlap) :]
+            if len(product_symbols) + len(addition) > max_product_length:
+                raise ConfigurationError("Assembly product exceeds max_product_length.")
+            product_symbols += addition
+            steps.append(
+                AssemblyStep(
+                    index=index,
+                    left_fragment_id=overlap_left.id,
+                    right_fragment_id=overlap_right.id,
+                    operation="exact_overlap_merge",
+                    junction_sequence=overlap,
+                )
+            )
+        if circularize:
+            closing = _resolve_overlap(
+                overlap_fragments[-1].sequence.symbols,
+                overlap_fragments[0].sequence.symbols,
+                explicit=None if overlap_values is None else overlap_values[-1],
+                minimum=min_overlap,
+                maximum=max_overlap,
+            )
+            if not product_symbols.endswith(closing):
+                raise ConfigurationError(
+                    "Closing overlap was consumed or altered by previous junctions."
+                )
+            product_symbols = product_symbols[: -len(closing)]
+            steps.append(
+                AssemblyStep(
+                    index=len(steps) + 1,
+                    left_fragment_id=overlap_fragments[-1].id,
+                    right_fragment_id=overlap_fragments[0].id,
+                    operation="circular_exact_overlap_merge",
+                    junction_sequence=closing,
+                )
+            )
+        if len(product_symbols) > max_product_length:
+            raise ConfigurationError("Assembly product exceeds max_product_length.")
+        alphabet = (
+            DNAAlphabet.IUPAC
+            if any(item.sequence.alphabet is DNAAlphabet.IUPAC for item in overlap_fragments)
+            else DNAAlphabet.STRICT
+        )
+        product = DNASequence(
+            product_symbols,
+            alphabet=alphabet,
+            topology=Topology.CIRCULAR if circularize else Topology.LINEAR,
+            strandedness=overlap_fragments[0].sequence.strandedness,
+        )
+    return AssemblyResult(
+        assembly_method=normalized_method,
+        product=product,
+        steps=tuple(steps),
+        circularized=circularize,
+        complete=True,
+        method="ordered_bounded_assembly_simulation",
+        algorithm_version="dnakit-assembly-v1",
+        parameters=freeze_parameters(
+            {
+                "assembly_method": normalized_method,
+                "fragment_count": len(materialized),
+                "min_overlap": min_overlap if normalized_method in ("gibson", "lcr") else None,
+                "max_overlap": max_overlap if normalized_method in ("gibson", "lcr") else None,
+                "explicit_overlaps": overlaps is not None,
+                "circularize": circularize,
+                "allow_blunt": allow_blunt,
+                "cycles": cycles,
+                "cycles_affect_sequence_result": False,
+                "kinetics_modeled": False,
+                "max_fragments": max_fragments,
+                "max_product_length": max_product_length,
+            }
+        ),
+        provenance=native_provenance(
+            reimplementation=True,
+            reference_name=f"{normalized_method} ordered assembly abstraction",
+            reference_version="boundary-v1",
+        ),
+        issues=issues,
+    )
+
+
+__all__ = ["AssemblyFragment", "simulate_assembly"]