factorforge-cds 3.0.0__py3-none-any.whl

factorforge/engines/v2/pipeline.py

@@ -0,0 +1,275 @@
+"""
+Optimization pipeline for FactorForge v2.
+Integrates validation, translation, rule scanning, domestication, and construct building.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from factorforge.engines.v2.construct_builder import ConstructBuilder
+from factorforge.engines.v2.rules.domesticator import Domesticator
+from factorforge.engines.v2.rules.reverse_translator import OptimizationProfile, ReverseTranslator
+from factorforge.engines.v2.rules.rule_engine import RuleEngine
+from factorforge.engines.v2.scoring import calculate_composite_score
+from factorforge.engines.v2.validator import InputValidator
+from factorforge.utils.construct_id import generate_construct_id
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from Bio.SeqRecord import SeqRecord
+
+
+@dataclass
+class PipelineResult:
+    """Pipeline output container."""
+
+    sequence: str
+    construct: "SeqRecord | None" = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def export_features(self) -> dict[str, Any]:
+        """schema.md 호환 피처 dict 반환 (purity_pct 제외 — 실험 후 수동 입력)."""
+        metrics = self.metadata.get("metrics", {})
+        scan = self.metadata.get("scan_results", {})
+        dom = self.metadata.get("domestication", {})
+
+        return {
+            "construct_id": self.metadata.get("construct_id", ""),
+            "protein_name": "",
+            "optimization_profile": self.metadata.get("profile", ""),
+            "cai_score": round(metrics.get("cai", 0.0), 4),
+            "gc_content_pct": round(metrics.get("gc", 0.0), 2),
+            "mfe_kcal_mol": round(metrics.get("mfe", 0.0), 2),
+            "polya_signal_count": len(scan.get("polya", [])),
+            "domestication_edits": len(dom.get("removed_sites", [])),
+            "sequence_length_aa": len(self.sequence) // 3,
+            "agro_od600": None,
+            "dpi": None,
+            "purity_pct": None,
+            "yield_mg_per_kg": None,
+        }
+
+    def save(self, filepath: Path, format: str = "fasta") -> None:
+        """
+        Save the result to a file.
+
+        Args:
+            filepath: Output file path.
+            format: "fasta" or "genbank".
+
+        Raises:
+            ImportError: If Biopython is required but not installed.
+        """
+        format_lower = format.lower()
+
+        if self.construct is not None and format_lower == "genbank":
+            try:
+                from Bio import SeqIO
+            except ImportError as exc:
+                raise ImportError("Biopython is required: pip install biopython") from exc
+
+            SeqIO.write(self.construct, str(filepath), "genbank")
+            return
+
+        with open(filepath, "w", encoding="utf-8") as handle:
+            handle.write(f">optimized\n{self.sequence}\n")
+
+
+class OptimizationPipeline:
+    """End-to-end v2 optimization pipeline."""
+
+    def __init__(
+        self,
+        profile: str = "balanced",
+        construct_template: str | None = None,
+        template_dir: Path | None = None,
+    ) -> None:
+        """
+        Args:
+            profile: Optimization profile name.
+            construct_template: Optional construct template name.
+            template_dir: Optional template directory.
+        """
+        self.profile = profile
+        self.construct_template = construct_template
+        self.template_dir = template_dir
+
+        self.validator = InputValidator()
+        self.translator = ReverseTranslator()
+        self.rule_engine = RuleEngine()
+        self.domesticator = Domesticator()
+
+        if construct_template:
+            if template_dir is None:
+                template_dir = Path(__file__).resolve().parents[4] / "data" / "templates"
+            self.construct_builder: ConstructBuilder | None = ConstructBuilder(template_dir)
+        else:
+            self.construct_builder = None
+
+    def run(
+        self,
+        sequence: str,
+        profile: str | None = None,
+        construct_template: str | None = None,
+        **kwargs: Any,
+    ) -> PipelineResult:
+        """
+        Run the optimization pipeline.
+
+        Args:
+            sequence: Input protein or DNA sequence.
+            profile: Optional profile override.
+            construct_template: Optional template override.
+            **kwargs: Additional settings.
+
+        Returns:
+            PipelineResult with sequence and metadata.
+
+        Raises:
+            ValueError: If input sequence is invalid.
+        """
+        logger.info(f"Starting optimization pipeline with profile: {profile or self.profile}")
+
+        val_result = self.validator.validate(sequence)
+        if not val_result["valid"]:
+            logger.error(f"Input validation failed: {val_result['errors']}")
+            raise ValueError(f"Invalid input sequence: {val_result['errors']}")
+
+        processed = val_result["processed_sequence"]
+        seq_type = val_result["type"]
+        logger.debug(f"Detected sequence type: {seq_type}")
+        if seq_type == "fasta":
+            seq_type = self.validator.detect_sequence_type(processed).value
+
+        effective_profile = (profile or self.profile or "balanced").lower()
+        try:
+            opt_profile = OptimizationProfile(effective_profile)
+        except ValueError as exc:
+            supported = ", ".join(p.value for p in OptimizationProfile)
+            raise ValueError(
+                f"Unknown profile: {effective_profile}. Supported profiles: {supported}"
+            ) from exc
+
+        if seq_type == "dna":
+            optimized_dna = processed
+            cai = self.translator.calculate_cai(optimized_dna)
+            gc = self.translator.calculate_gc_content(optimized_dna)
+            score = calculate_composite_score(
+                cai=cai, gc=gc, sequence=optimized_dna, profile=effective_profile
+            )
+            candidate_metrics = {"cai": cai, "gc": gc, "score": score}
+        else:
+            logger.debug(f"Generating candidates with profile: {opt_profile.value}")
+            candidates = self.translator.generate_candidates(processed, profile=opt_profile, n=1)
+            if not candidates:
+                logger.error("No candidates generated for input sequence")
+                raise ValueError("No candidates generated for input sequence.")
+            optimized_dna = candidates[0]["sequence"]
+            candidate_metrics = {
+                "cai": candidates[0]["cai"],
+                "gc": candidates[0]["gc"],
+                "score": candidates[0]["score"],
+            }
+            logger.info(
+                f"Generated optimized sequence: CAI={candidate_metrics['cai']:.3f}, "
+                f"GC={candidate_metrics['gc']:.1f}%"
+            )
+
+        # Fast pre-check avoids an expensive full rule scan before PolyA fixing.
+        has_polya_signal = any(
+            pattern in optimized_dna for pattern in self.rule_engine.POLYA_PATTERNS
+        )
+        if has_polya_signal:
+            logger.debug("Potential PolyA signal detected; attempting iterative fix")
+            polya_fix = self.rule_engine.fix_polya_iterative(optimized_dna)
+            if polya_fix["success"]:
+                optimized_dna = polya_fix["modified_seq"]
+                logger.info(
+                    f"Fixed {len(polya_fix['fixes_applied'])} PolyA violation(s) "
+                    f"in {polya_fix['rounds']} round(s)"
+                )
+            else:
+                logger.warning(
+                    f"Could not fix all PolyA violations. "
+                    f"Remaining: {polya_fix.get('remaining_violations', '?')}"
+                )
+
+        logger.debug("Scanning for final rule violations")
+        scan_mode = str(kwargs.get("scan_mode", "full"))
+        scan_include = kwargs.get("scan_include")
+        scan_exclude = kwargs.get("scan_exclude")
+        scan_results = self.rule_engine.scan_all(
+            optimized_dna,
+            mode=scan_mode,
+            include=scan_include,
+            exclude=scan_exclude,
+        )
+
+        assembly_standard = kwargs.get("assembly_standard", "golden_gate")
+        domestication = self.domesticator.domesticate(optimized_dna, standard=assembly_standard)
+        domesticated_sequence = domestication.get("domesticated_seq", optimized_dna)
+
+        template_name = construct_template or self.construct_template
+        if template_name:
+            if self.construct_builder is None:
+                template_dir = (
+                    self.template_dir or Path(__file__).resolve().parents[4] / "data" / "templates"
+                )
+                self.construct_builder = ConstructBuilder(template_dir)
+            construct_record = self.construct_builder.generate_construct(
+                gene_sequence=domesticated_sequence,
+                template_name=template_name,
+            )
+            final_sequence = str(construct_record.seq)
+        else:
+            construct_record = None
+            final_sequence = domesticated_sequence
+
+        metadata: dict[str, Any] = {
+            "construct_id": generate_construct_id(),
+            "profile": effective_profile,
+            "construct_template": template_name,
+            "construct_features": len(construct_record.features) if construct_record else 0,
+            "validation": val_result,
+            "scan_results": scan_results,
+            "domestication": domestication,
+            "metrics": candidate_metrics,
+            "scan_mode": scan_mode,
+        }
+
+        return PipelineResult(
+            sequence=final_sequence,
+            construct=construct_record,
+            metadata=metadata,
+        )
+
+    def run_batch(
+        self,
+        sequences: list[dict[str, str]] | list[str],
+        profile: str | None = None,
+        construct_template: str | None = None,
+        **kwargs: Any,
+    ) -> list[PipelineResult]:
+        """Run the optimization pipeline for a batch of sequences."""
+        results: list[PipelineResult] = []
+        for idx, entry in enumerate(sequences, start=1):
+            if isinstance(entry, dict):
+                seq = entry.get("sequence", "")
+                seq_id = entry.get("id", f"seq{idx}")
+            else:
+                seq = entry
+                seq_id = f"seq{idx}"
+            result = self.run(
+                seq,
+                profile=profile,
+                construct_template=construct_template,
+                **kwargs,
+            )
+            result.metadata["input_id"] = seq_id
+            results.append(result)
+        return results

factorforge/engines/v2/rules/__init__.py

@@ -0,0 +1,3 @@
+"""Rule-based optimization rules"""
+
+# TODO: Add PolyA scanner, domesticator, etc.

factorforge/engines/v2/rules/domesticator.py

@@ -0,0 +1,403 @@
+"""
+Domesticator for FactorForge v2
+Assembly standard compatibility (P0-4) - Golden Gate/MoClo/BioBricks
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from factorforge.engines.v2.utils import build_aa_to_codons_map, load_codon_table
+
+
+class Domesticator:
+    """
+    Remove restriction enzyme sites for assembly compatibility
+
+    Supported assembly systems:
+    - Golden Gate (BsaI, BpiI, BsmBI)
+    - MoClo (BsaI + overhangs)
+    - BioBricks (EcoRI, XbaI, SpeI, PstI)
+    """
+
+    # Assembly standard definitions
+    ASSEMBLY_STANDARDS: dict[str, dict[str, Any]] = {
+        "golden_gate": {
+            "enzymes": ["BsaI", "BpiI", "BsmBI"],
+            "sites": {
+                "BsaI": ["GGTCTC", "GAGACC"],  # Forward and reverse complement
+                "BpiI": ["GAAGAC", "GTCTTC"],
+                "BsmBI": ["CGTCTC", "GAGACG"],
+            },
+        },
+        "moclo": {
+            "enzymes": ["BsaI"],
+            "sites": {"BsaI": ["GGTCTC", "GAGACC"]},
+            "overhangs": ["AATG", "AGGT", "GCTT", "CGCT"],  # Level 0
+        },
+        "biobricks": {
+            "enzymes": ["EcoRI", "XbaI", "SpeI", "PstI"],
+            "sites": {
+                "EcoRI": ["GAATTC"],
+                "XbaI": ["TCTAGA"],
+                "SpeI": ["ACTAGT"],
+                "PstI": ["CTGCAG"],
+            },
+        },
+    }
+
+    def __init__(self, codon_table: dict[str, Any] | None = None) -> None:
+        """
+        Args:
+            codon_table: Codon table (loads default if None)
+        """
+        if codon_table is None:
+            # Load from default path
+            project_root = Path(__file__).resolve().parents[5]
+            codon_table = load_codon_table("nbenthamiana", project_root / "data")
+
+        self.codon_table: dict[str, Any] = codon_table
+        self.aa_to_codons: dict[str, list[str]] = self._build_aa_to_codons_map()
+
+    def _build_aa_to_codons_map(self) -> dict[str, list[str]]:
+        """Build amino-acid-to-codons map"""
+        return build_aa_to_codons_map(self.codon_table)
+
+    def scan_restriction_sites(
+        self,
+        seq: str,
+        standard: str = "golden_gate",
+    ) -> list[dict[str, Any]]:
+        """
+        Scan restriction enzyme sites
+
+        Args:
+            seq: DNA sequence
+            standard: Assembly standard ("golden_gate", "moclo", "biobricks")
+
+        Returns:
+            List of detected sites
+
+        Raises:
+            ValueError: Unsupported assembly standard.
+
+        Examples:
+            >>> domesticator = Domesticator()
+            >>> domesticator.scan_restriction_sites("GGTCTC", "golden_gate")
+            [{'enzyme': 'BsaI', ...}]
+        """
+        if standard not in self.ASSEMBLY_STANDARDS:
+            raise ValueError(f"Unknown assembly standard: {standard}")
+
+        assembly_info = self.ASSEMBLY_STANDARDS[standard]
+        sites_found: list[dict[str, Any]] = []
+
+        for enzyme, site_seqs in assembly_info["sites"].items():
+            for site_seq in site_seqs:
+                pos = 0
+                while True:
+                    idx = seq.find(site_seq, pos)
+                    if idx == -1:
+                        break
+
+                    sites_found.append(
+                        {
+                            "enzyme": enzyme,
+                            "site": site_seq,
+                            "position": idx,
+                            "context": seq[
+                                max(0, idx - 10) : min(len(seq), idx + len(site_seq) + 10)
+                            ],
+                        }
+                    )
+                    pos = idx + 1
+
+        return sites_found
+
+    def domesticate(
+        self,
+        seq: str,
+        standard: str = "golden_gate",
+        max_attempts: int = 100,
+    ) -> dict[str, Any]:
+        """
+        Remove restriction enzyme sites
+
+        Args:
+            seq: DNA sequence
+            standard: Assembly standard
+            max_attempts: Maximum attempts
+
+        Returns:
+            {
+                "domesticated_seq": "...",
+                "removed_sites": [...],
+                "unfixable": [...],
+                "success": True/False
+            }
+
+        Raises:
+            ValueError: Unsupported assembly standard.
+
+        Examples:
+            >>> domesticator = Domesticator()
+            >>> result = domesticator.domesticate("ATGGGTCTCGAG", "golden_gate")
+            >>> "domesticated_seq" in result
+            True
+        """
+        if len(seq) % 3 != 0:
+            return {
+                "success": False,
+                "error": "Sequence length not divisible by 3",
+                "domesticated_seq": seq,
+            }
+
+        modified_seq = seq
+        removed_sites: list[dict[str, Any]] = []
+        unfixable: list[dict[str, Any]] = []
+
+        # Iteratively remove sites
+        for attempt in range(max_attempts):
+            sites = self.scan_restriction_sites(modified_seq, standard)
+
+            if not sites:
+                # All sites removed
+                return {
+                    "success": True,
+                    "domesticated_seq": modified_seq,
+                    "removed_sites": removed_sites,
+                    "unfixable": [],
+                    "attempts": attempt + 1,
+                }
+
+            # Attempt to remove the first site
+            site = sites[0]
+            result = self._remove_site(modified_seq, site)
+
+            if result["success"]:
+                modified_seq = result["modified_seq"]
+                removed_sites.append(
+                    {
+                        "enzyme": site["enzyme"],
+                        "position": site["position"],
+                        "changes": result["changes"],
+                    }
+                )
+            else:
+                # Failed to remove site
+                unfixable.append(
+                    {
+                        "enzyme": site["enzyme"],
+                        "site": site["site"],
+                        "position": site["position"],
+                        "reason": result.get("reason", "Unknown"),
+                        "alternatives": self._suggest_alternatives(seq, site),
+                    }
+                )
+                # Record as unfixable and continue to next site
+                continue
+
+        # Sites still remain after max attempts
+        remaining_sites = self.scan_restriction_sites(modified_seq, standard)
+
+        return {
+            "success": len(remaining_sites) == 0,
+            "domesticated_seq": modified_seq,
+            "removed_sites": removed_sites,
+            "unfixable": unfixable if unfixable else remaining_sites,
+            "attempts": max_attempts,
+        }
+
+    def _remove_site(self, seq: str, site: dict[str, Any]) -> dict[str, Any]:
+        """
+        Remove a single restriction enzyme site
+
+        Args:
+            seq: DNA sequence
+            site: Site info
+
+        Returns:
+            {
+                "success": True/False,
+                "modified_seq": "...",
+                "changes": [...]
+            }
+        """
+        pos = site["position"]
+        site_seq = site["site"]
+        site_len = len(site_seq)
+
+        # Compute codon range overlapping the site
+        first_codon_idx = (pos // 3) * 3
+        last_codon_idx = ((pos + site_len - 1) // 3) * 3
+
+        # Try synonymous substitutions per codon
+        for codon_start in range(first_codon_idx, last_codon_idx + 1, 3):
+            if codon_start + 3 > len(seq):
+                continue
+
+            original_codon = seq[codon_start : codon_start + 3]
+
+            # Validate amino acid
+            if original_codon not in self.codon_table["codons"]:
+                continue
+
+            aa = self.codon_table["codons"][original_codon]["aa"]
+
+            # Find synonymous codons
+            synonymous_codons = [c for c in self.aa_to_codons.get(aa, []) if c != original_codon]
+
+            if not synonymous_codons:
+                continue
+
+            # Try each synonymous codon
+            for alt_codon in synonymous_codons:
+                # Temporary substitution
+                test_seq = seq[:codon_start] + alt_codon + seq[codon_start + 3 :]
+
+                # Check if site is gone
+                test_region = test_seq[max(0, pos - 10) : min(len(test_seq), pos + site_len + 10)]
+
+                if site_seq not in test_region:
+                    # Success
+                    return {
+                        "success": True,
+                        "modified_seq": test_seq,
+                        "changes": [
+                            {
+                                "pos": codon_start,
+                                "original": original_codon,
+                                "fixed": alt_codon,
+                                "aa": aa,
+                            }
+                        ],
+                    }
+
+        # Failed to fix
+        return {
+            "success": False,
+            "modified_seq": seq,
+            "changes": [],
+            "reason": "No synonymous codon available to remove site",
+        }
+
+    def _suggest_alternatives(self, seq: str, site: dict[str, Any]) -> list[str]:
+        """
+        Suggest alternatives for unremovable sites
+
+        Args:
+            seq: DNA sequence
+            site: Site info
+
+        Returns:
+            List of alternative suggestions
+        """
+        alternatives: list[str] = []
+
+        pos = site["position"]
+        site_len = len(site["site"])
+
+        # Determine affected codons
+        first_codon_idx = (pos // 3) * 3
+        last_codon_idx = ((pos + site_len - 1) // 3) * 3
+
+        affected_codons: list[dict[str, Any]] = []
+        for codon_start in range(first_codon_idx, last_codon_idx + 1, 3):
+            if codon_start + 3 <= len(seq):
+                codon = seq[codon_start : codon_start + 3]
+                if codon in self.codon_table["codons"]:
+                    aa = self.codon_table["codons"][codon]["aa"]
+                    synonymous = self.aa_to_codons.get(aa, [])
+                    affected_codons.append(
+                        {
+                            "pos": codon_start,
+                            "codon": codon,
+                            "aa": aa,
+                            "synonymous_count": len(synonymous) - 1,
+                        }
+                    )
+
+        # Suggest alternatives
+        if any(c["synonymous_count"] == 0 for c in affected_codons):
+            alternatives.append(
+                "Includes amino acids without synonyms - requires non-synonymous change"
+            )
+
+        alternatives.append("Try shifting the site by adjusting adjacent codons")
+
+        alternatives.append("Consider using a different assembly method")
+
+        return alternatives
+
+    def batch_domesticate(
+        self,
+        sequences: list[dict[str, Any]],
+        standard: str = "golden_gate",
+    ) -> list[dict[str, Any]]:
+        """
+        Batch domestication
+
+        Args:
+            sequences: [{"id": "gene1", "sequence": "ATG..."}, ...]
+            standard: Assembly standard
+
+        Returns:
+            List of results
+
+        Raises:
+            ValueError: Unsupported assembly standard.
+
+        Examples:
+            >>> domesticator = Domesticator()
+            >>> results = domesticator.batch_domesticate([{"id": "x", "sequence": "ATG"}])
+            >>> len(results)
+            1
+        """
+        results: list[dict[str, Any]] = []
+
+        for seq_data in sequences:
+            seq_id = seq_data.get("id", "unknown")
+            seq = seq_data.get("sequence", "")
+
+            result = self.domesticate(seq, standard)
+            result["id"] = seq_id
+            results.append(result)
+
+        return results
+
+
+# --- Usage example ---
+if __name__ == "__main__":
+    domesticator = Domesticator()
+
+    # Test sequence (includes BsaI site)
+    test_seq = "ATGGGTCTCGAGGAGCTGTTCACCGGGGTGGTGCCCATC"
+
+    print("=== Original Sequence ===")
+    print(f"Sequence: {test_seq}")
+
+    # Golden Gate scan
+    sites = domesticator.scan_restriction_sites(test_seq, "golden_gate")
+    print(f"\nRestriction sites found: {len(sites)}")
+    for site in sites:
+        print(f"  - {site['enzyme']} at position {site['position']}: {site['site']}")
+
+    # Domestication
+    print("\n=== Domestication ===")
+    result = domesticator.domesticate(test_seq, "golden_gate")
+
+    if result["success"]:
+        print("✅ Domestication successful!")
+        print(f"Modified sequence: {result['domesticated_seq']}")
+        print(f"Removed sites: {len(result['removed_sites'])}")
+        for removed in result["removed_sites"]:
+            print(f"  - {removed['enzyme']} at position {removed['position']}")
+    else:
+        print("❌ Domestication failed")
+        print(f"Unfixable sites: {len(result['unfixable'])}")
+        for unfixable in result["unfixable"]:
+            print(
+                f"  - {unfixable.get('enzyme', 'N/A')} at position {unfixable.get('position', 'N/A')}"
+            )
+            print(f"    Alternatives: {unfixable.get('alternatives', [])}")