factorforge-cds 3.1.8__tar.gz → 3.1.9__tar.gz

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.1.8
+Version: 3.1.9
 Summary: FactorForge - open-source constraint-based CDS design engine by Eijex.
 Author-email: Eijex <eijex.lab@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -107,7 +107,7 @@ FactorForge predictions are **in-silico only** and have not been experimentally
 ## Citing
 
 ```
-FactorForge v3.1.8 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.1.9 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/README.md

@@ -76,7 +76,7 @@ FactorForge predictions are **in-silico only** and have not been experimentally
 ## Citing
 
 ```
-FactorForge v3.1.8 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.1.9 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.1.8"
+version = "3.1.9"
 description = "FactorForge - open-source constraint-based CDS design engine by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/__init__.py

@@ -4,7 +4,7 @@ FactorForge - Codon Optimization Platform
 profile: constraint-aware rule/profile engine
 """
 
-__version__ = "3.1.8"
+__version__ = "3.1.9"
 __author__ = "Eijex"
 
 # Auto-register engines (safe when running from source tree)

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/analysis/metrics.py

@@ -277,6 +277,32 @@ def calculate_cai(sequence: str, codon_weights: dict[str, float]) -> float:
     return math.exp(log_sum / count) if count else 0.0
 
 
+def calculate_dinucleotide_score(
+    sequence: str,
+    cpg_weight: float = 0.0,
+    tpa_weight: float = 1.0,
+) -> float:
+    """Score dinucleotide avoidance.
+
+    Plant default: CpG inactive (cpg_weight=0.0), only TpA is penalized.
+    Mammalian opt-in: set cpg_weight=1.0 and tpa_weight=1.0 to penalize both.
+    """
+    from factorforge.engines.profile.utils import calculate_dinucleotide_ratio
+
+    if len(sequence) < 6:
+        return 1.0
+
+    total_weight = cpg_weight + tpa_weight
+    if total_weight == 0:
+        return 1.0
+
+    cpg_ratio = calculate_dinucleotide_ratio(sequence, "CG")
+    tpa_ratio = calculate_dinucleotide_ratio(sequence, "TA")
+    cpg_score = max(0.0, 1.0 - cpg_ratio / 2.0)
+    tpa_score = max(0.0, 1.0 - tpa_ratio / 2.0)
+    return (cpg_weight * cpg_score + tpa_weight * tpa_score) / total_weight
+
+
 def codon_usage_profile(sequence: str) -> dict[str, dict[str, float | int | str]]:
     """Return codon counts and frequencies for a DNA sequence."""
     codons = _codons(sequence)

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/engines/__init__.py

@@ -13,7 +13,7 @@ def register_builtin_engines() -> None:
         "profile",
         RuleBasedOptimizer,
         metadata={
-            "version": "3.1.8",
+            "version": "3.1.9",
             "engine_type": "profile_rule_based",
             "role": "stable_profile_engine",
             "stable": True,

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/__init__.py

@@ -5,7 +5,7 @@ Production system (2026)
 Plant-specific rule-based optimization
 """
 
-__version__ = "3.1.8"
+__version__ = "3.1.9"
 
 from .optimizer import RuleBasedOptimizer
 from .pipeline import OptimizationPipeline

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/optimizer.py

@@ -9,7 +9,7 @@ from factorforge.core.interfaces import OptimizationResult, OptimizerEngine
 from .exporter import SequenceExporter
 from .rules.reverse_translator import OptimizationProfile, ReverseTranslator
 from .rules.rule_engine import RuleEngine
-from .scoring import calculate_composite_score
+from .scoring import calculate_composite_score, compute_mfe_evidence
 from .validator import InputValidator
 
 
@@ -17,7 +17,7 @@ class RuleBasedOptimizer(OptimizerEngine):
     """Profile-based rule optimization engine."""
 
     name = "Profile-based"
-    version = "3.1.8"
+    version = "3.1.9"
 
     def __init__(self) -> None:
         self.validator = InputValidator()
@@ -117,6 +117,10 @@ class RuleBasedOptimizer(OptimizerEngine):
             "score": candidates[0]["score"],
             "violations": sum(len(v) for v in scan_results.values()),
         }
+        # MFE provenance: expose whether MFE was actually computed so downstream
+        # artifacts (API response, Design Package) never report an uncomputed
+        # MFE as a misleading 0.0 (016 audit). Score value is unchanged.
+        metrics.update(compute_mfe_evidence(optimized_dna, profile=profile_value))
 
         return OptimizationResult(
             sequence=optimized_dna,

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/pipeline.py

@@ -18,9 +18,14 @@ from factorforge.engines.profile.rules.reverse_translator import (
     ReverseTranslator,
 )
 from factorforge.engines.profile.rules.rule_engine import RuleEngine
-from factorforge.engines.profile.scoring import calculate_composite_score
+from factorforge.engines.profile.scoring import (
+    calculate_composite_score,
+    compute_mfe_evidence,
+)
 from factorforge.engines.profile.validator import InputValidator
+from factorforge.analysis.metrics import translate_dna
 from factorforge.utils.construct_id import generate_construct_id
+from factorforge.utils.sequence_validator import validate_cds_output
 
 logger = logging.getLogger(__name__)
 
@@ -48,7 +53,15 @@ class PipelineResult:
             "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),
+            # MFE provenance (016 audit): None when not computed (e.g. ViennaRNA
+            # unavailable) — never report an uncomputed MFE as a misleading 0.0.
+            "mfe_kcal_mol": (
+                round(metrics["mfe_kcal_mol"], 2)
+                if metrics.get("mfe_kcal_mol") is not None
+                else None
+            ),
+            "mfe_status": metrics.get("mfe_status", "not_computed"),
+            "mfe_used": metrics.get("mfe_used", False),
             "polya_signal_count": len(scan.get("polya", [])),
             "domestication_edits": len(dom.get("removed_sites", [])),
             "sequence_length_aa": len(self.sequence) // 3,
@@ -175,6 +188,7 @@ class OptimizationPipeline:
 
         if seq_type == "dna":
             optimized_dna = processed
+            expected_protein = translate_dna(processed).rstrip("*")
             cai = translator.calculate_cai(optimized_dna)
             gc = translator.calculate_gc_content(optimized_dna)
             score = calculate_composite_score(
@@ -182,6 +196,7 @@ class OptimizationPipeline:
             )
             candidate_metrics = {"cai": cai, "gc": gc, "score": score}
         else:
+            expected_protein = processed.rstrip("*")
             logger.debug(f"Generating candidates with profile: {opt_profile.value}")
             candidates = translator.generate_candidates(processed, profile=opt_profile, n=1)
             if not candidates:
@@ -251,7 +266,20 @@ class OptimizationPipeline:
 
         assembly_standard = kwargs.get("assembly_standard", "golden_gate")
         domestication = domesticator.domesticate(optimized_dna, standard=assembly_standard)
+        if not domestication.get("success", False):
+            unfixable = domestication.get("unfixable", [])
+            error = domestication.get("error")
+            detail = error or f"unfixable restriction sites: {unfixable}"
+            raise ValueError(f"Domestication failed for {assembly_standard}: {detail}")
+
         domesticated_sequence = domestication.get("domesticated_seq", optimized_dna)
+        final_validation = validate_cds_output(expected_protein, domesticated_sequence)
+        if not final_validation["passed"]:
+            raise ValueError(
+                "Final CDS validation failed: "
+                f"{final_validation['errors']} "
+                f"(aa_identity={final_validation['aa_identity']:.4f})"
+            )
 
         template_name = construct_template or self.construct_template
         if template_name:
@@ -269,6 +297,13 @@ class OptimizationPipeline:
             construct_record = None
             final_sequence = domesticated_sequence
 
+        # MFE provenance for the final output sequence (016 audit): record
+        # whether MFE was computed so export_features / Design Package never
+        # report an uncomputed MFE as 0.0.
+        candidate_metrics.update(
+            compute_mfe_evidence(domesticated_sequence, profile=effective_profile)
+        )
+
         metadata: dict[str, Any] = {
             "construct_id": generate_construct_id(),
             "profile": effective_profile,
@@ -278,6 +313,7 @@ class OptimizationPipeline:
             "validation": val_result,
             "scan_results": scan_results,
             "domestication": domestication,
+            "final_validation": final_validation,
             "metrics": candidate_metrics,
             "scan_mode": scan_mode,
         }

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/rules/reverse_translator.py

@@ -551,8 +551,8 @@ class ReverseTranslator:
         """Apply N-terminal codon ramp for co-translational folding.
 
         Replaces the first `ramp_codons` codons with lower-frequency synonymous
-        codons (bottom 50% by frequency) to slow the ribosome at the N-terminus.
-        Single-codon amino acids (Met, Trp) are left unchanged.
+        codons (bottom 25% by frequency; cutoff = 3*len//4) to slow the ribosome
+        at the N-terminus. Single-codon amino acids (Met, Trp) are left unchanged.
 
         TODO: ramp profile is currently not in VALID_PROFILES (not publicly accessible).
         Before re-enabling, revisit ramp_codons=50:

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/rules/rule_engine.py

@@ -354,13 +354,20 @@ class RuleEngine:
         max_gc: float = 75,
     ) -> list[dict[str, Any]]:
         """
-        Detect extreme GC regions
+        Detect extreme GC regions in a sliding local window.
+
+        This is a LOCAL synthesis/extreme-window guard (default 25-75% over a
+        50 bp window), NOT the global GC target. Global GC is governed separately
+        by the scoring band (GC_OPT_MIN/MAX, ~55-65%) and the API/DP gc_min/gc_max
+        constraints. The wide 25-75% band intentionally flags only synthesis-hostile
+        local windows; narrowing it toward the global optimum would raise false
+        positives against the engine's own output distribution (analysis 004: 55-71%).
 
         Args:
             seq: DNA sequence
             window: Window size (bp)
-            min_gc: Minimum GC% threshold
-            max_gc: Maximum GC% threshold
+            min_gc: Minimum local GC% threshold (synthesis guard, not global target)
+            max_gc: Maximum local GC% threshold (synthesis guard, not global target)
 
         Returns:
             List of violations

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/scoring.py

@@ -34,6 +34,8 @@ class ScoringConfig:
     w_gc: float = 0.3
     w_mfe: float = 0.2
     w_dinuc: float = 0.0  # CpG/TpA dinucleotide penalty (opt-in, default off)
+    cpg_weight: float = 0.0  # plant default: CpG inactive
+    tpa_weight: float = 1.0  # plant default: TpA active
     w_syncodonlm: float = 0.0  # SynCodonLM quality score (opt-in, default off)
     gc_opt: float = GC_OPT_MID  # no longer used by calculate_composite_score (superseded by
                                 # gc_min/gc_max band); retained for external API compatibility
@@ -187,31 +189,19 @@ def gc_band_score(
     return max(0.0, 1.0 - distance / decay_width)
 
 
-def calculate_dinucleotide_score(sequence: str) -> float:
-    """Calculate a dinucleotide avoidance score (0-1, higher = fewer CpG/TpA).
-
-    Combines CpG and TpA observed/expected ratios. A sequence with no CpG
-    and no TpA scores 1.0; high density scores toward 0.0.
-
-    Args:
-        sequence: DNA sequence.
+def calculate_dinucleotide_score(
+    sequence: str,
+    cpg_weight: float = 0.0,
+    tpa_weight: float = 1.0,
+) -> float:
+    """Score dinucleotide avoidance.
 
-    Returns:
-        Dinucleotide avoidance score (0-1).
+    Plant default: CpG inactive (cpg_weight=0.0), only TpA is penalized.
+    Mammalian opt-in: set cpg_weight=1.0 and tpa_weight=1.0 to penalize both.
     """
-    from factorforge.engines.profile.utils import calculate_dinucleotide_ratio
+    from factorforge.analysis.metrics import calculate_dinucleotide_score as _score
 
-    if len(sequence) < 6:
-        return 1.0
-
-    cpg_ratio = calculate_dinucleotide_ratio(sequence, "CG")
-    tpa_ratio = calculate_dinucleotide_ratio(sequence, "TA")
-
-    # Score: 1.0 when ratio=0, 0.0 when ratio>=2.0
-    cpg_score = max(0.0, 1.0 - cpg_ratio / 2.0)
-    tpa_score = max(0.0, 1.0 - tpa_ratio / 2.0)
-
-    return (cpg_score + tpa_score) / 2.0
+    return _score(sequence, cpg_weight=cpg_weight, tpa_weight=tpa_weight)
 
 
 def calculate_composite_score(
@@ -279,7 +269,11 @@ def calculate_composite_score(
     dinuc_score = 0.5  # neutral default
     actual_w_dinuc = config.w_dinuc
     if actual_w_dinuc > 0 and sequence is not None:
-        dinuc_score = calculate_dinucleotide_score(sequence)
+        dinuc_score = calculate_dinucleotide_score(
+            sequence,
+            cpg_weight=config.cpg_weight,
+            tpa_weight=config.tpa_weight,
+        )
     elif actual_w_dinuc > 0:
         actual_w_dinuc = 0.0  # Cannot compute without sequence
 
@@ -308,3 +302,50 @@ def calculate_composite_score(
     )
 
     return round(score, 3)
+
+
+def compute_mfe_evidence(
+    sequence: str | None,
+    config: ScoringConfig | None = None,
+    profile: str | None = None,
+) -> dict[str, Any]:
+    """Return MFE provenance metadata for a scored sequence.
+
+    Mirrors the MFE branch of ``calculate_composite_score`` WITHOUT changing the
+    score. Its purpose is honesty: when MFE is not computed (e.g. ViennaRNA is
+    unavailable in the deployment, as on Vercel), callers must be able to tell
+    that ``mfe_kcal_mol`` is absent rather than a genuine 0.0.
+
+    Returns a dict with:
+        mfe_kcal_mol: float | None   (None when not computed)
+        mfe_status:   "computed" | "not_computed"
+        mfe_used:     bool           (whether MFE contributed to the score)
+        mfe_warning:  str | None     (reason when not used)
+        score_components: {cai_used, gc_used, mfe_used}
+    """
+    if config is None:
+        profile_name = (profile or "balanced").lower()
+        config = PROFILE_SCORING_CONFIGS.get(profile_name) or PROFILE_SCORING_CONFIGS["balanced"]
+
+    mfe_value: float | None = None
+    reason: str | None = None
+
+    if not config.use_mfe:
+        reason = "MFE scoring is disabled for this profile."
+    elif sequence is None:
+        reason = "MFE was not computed because no sequence was provided."
+    elif not _check_vienna_available():
+        reason = "MFE was not computed because ViennaRNA is unavailable in this environment."
+    else:
+        mfe_value = calculate_mfe(sequence)
+        if mfe_value is None:
+            reason = "MFE computation failed for this sequence."
+
+    mfe_used = mfe_value is not None
+    return {
+        "mfe_kcal_mol": round(mfe_value, 2) if mfe_used else None,
+        "mfe_status": "computed" if mfe_used else "not_computed",
+        "mfe_used": mfe_used,
+        "mfe_warning": None if mfe_used else reason,
+        "score_components": {"cai_used": True, "gc_used": True, "mfe_used": mfe_used},
+    }

{factorforge_cds-3.1.8 → factorforge_cds-3.1.9}/src/factorforge_cds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.1.8
+Version: 3.1.9
 Summary: FactorForge - open-source constraint-based CDS design engine by Eijex.
 Author-email: Eijex <eijex.lab@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -107,7 +107,7 @@ FactorForge predictions are **in-silico only** and have not been experimentally
 ## Citing
 
 ```
-FactorForge v3.1.8 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.1.9 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```