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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.1.7
+Version: 3.1.8
 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.7 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.1.8 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.1.7"
+version = "3.1.8"
 description = "FactorForge - open-source constraint-based CDS design engine by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -56,6 +56,7 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 norecursedirs = ["archive"]
+pythonpath = ["src"]
 
 [tool.ruff]
 line-length = 100

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

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

{factorforge_cds-3.1.7 → factorforge_cds-3.1.8}/src/factorforge/analysis/feasibility.py

@@ -88,9 +88,9 @@ def _reconstruct_sequence(
 def analyze_feasibility(
     protein_sequence: str,
     codon_weights: dict[str, float],
-    target_cai: float = 0.92,
-    target_gc_low: float = 41.0,
-    target_gc_high: float = 44.0,
+    target_cai: float = 0.82,
+    target_gc_low: float = 55.0,
+    target_gc_high: float = 65.0,
     gc_ranges: list[tuple[float, float]] | None = None,
 ) -> dict[str, Any]:
     """Compute exact CAI/GC feasibility over synonymous codon choices.
@@ -98,12 +98,16 @@ def analyze_feasibility(
     The dynamic program keeps the best log-CAI sequence for each reachable
     global GC count. This is exact for global GC and CAI under the supplied
     codon weights.
+
+    Defaults calibrated to nbenthamiana profile engine output distribution
+    (analysis 004, n=49): avg CAI=0.76, avg GC=60.1% (range 55-71%).
+    target_cai=0.82 aligns with industry practice (>0.8) and is achievable.
     """
     protein = "".join(protein_sequence.upper().split()).rstrip("*")
     if not protein:
         raise ValueError("protein_sequence must not be empty")
 
-    ranges = gc_ranges or [(41.0, 44.0), (40.0, 50.0), (40.0, 55.0)]
+    ranges = gc_ranges or [(55.0, 65.0), (50.0, 65.0), (40.0, 65.0)]
     normalized_ranges = [
         (_normalize_gc_bound(low), _normalize_gc_bound(high)) for low, high in ranges
     ]

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

@@ -11,6 +11,12 @@ from typing import Any
 
 from factorforge.engines.profile.utils import get_data_path
 
+# Homopolymer thresholds — two distinct concerns, intentionally different values.
+# Expression stability: AT-rich runs ≥6 nt can resemble instability elements (ARE).
+# Synthesis/manufacturing: runs ≥8 nt are flagged by gene synthesis vendors as difficult.
+HOMOPOLYMER_EXPRESSION_WARN_NT = 6
+HOMOPOLYMER_SYNTHESIS_WARN_NT = 8
+
 
 STANDARD_GENETIC_CODE: dict[str, str] = {
     "TTT": "F",
@@ -286,8 +292,19 @@ def codon_usage_profile(sequence: str) -> dict[str, dict[str, float | int | str]
     return profile
 
 
-def detect_homopolymers(sequence: str, max_run: int = 6) -> list[dict[str, Any]]:
-    """Detect runs whose length is greater than or equal to max_run."""
+def detect_homopolymers(
+    sequence: str,
+    max_run: int = HOMOPOLYMER_EXPRESSION_WARN_NT,
+) -> list[dict[str, Any]]:
+    """Detect homopolymer runs for expression stability evaluation.
+
+    Uses HOMOPOLYMER_EXPRESSION_WARN_NT (default 6 nt) — AT-rich runs of this
+    length can resemble AU-rich instability elements (ARE) and affect mRNA
+    stability in plant expression systems.
+
+    For synthesis/manufacturing risk, see RuleEngine.scan_homopolymers()
+    which uses HOMOPOLYMER_SYNTHESIS_WARN_NT (8 nt).
+    """
     if max_run <= 1:
         raise ValueError("max_run must be > 1")
 
@@ -303,17 +320,27 @@ def detect_homopolymers(sequence: str, max_run: int = 6) -> list[dict[str, Any]]
             continue
         run_length = index - run_start
         if run_length >= max_run:
-            findings.append(
-                {"start": run_start, "end": index, "base": run_base, "length": run_length}
-            )
+            findings.append({
+                "start": run_start,
+                "end": index,
+                "base": run_base,
+                "length": run_length,
+                "context": "expression_stability",
+                "threshold_nt": max_run,
+            })
         run_base = base
         run_start = index
 
     run_length = len(seq) - run_start
     if run_length >= max_run:
-        findings.append(
-            {"start": run_start, "end": len(seq), "base": run_base, "length": run_length}
-        )
+        findings.append({
+            "start": run_start,
+            "end": len(seq),
+            "base": run_base,
+            "length": run_length,
+            "context": "expression_stability",
+            "threshold_nt": max_run,
+        })
     return findings
 
 

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

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

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

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

{factorforge_cds-3.1.7 → factorforge_cds-3.1.8}/src/factorforge/engines/profile/exporter.py

@@ -6,8 +6,10 @@ GenBank and FASTA export module (P0-5)
 from __future__ import annotations
 
 import hashlib
+import json
 from datetime import datetime
 from io import StringIO
+from pathlib import Path
 from typing import Any
 
 
@@ -25,6 +27,26 @@ class SequenceExporter:
         """Initialize"""
         pass
 
+    def host_species(self, metadata: dict[str, Any]) -> str:
+        """Resolve host species from feature_registry.json when possible."""
+        if metadata.get("organism"):
+            return str(metadata["organism"])
+
+        host = str(
+            metadata.get("host_profile") or metadata.get("host") or "nbenthamiana"
+        ).strip().lower()
+        host_aliases = {"ntabacum": "by2"}
+        registry_key = host_aliases.get(host, host)
+        registry_path = Path(__file__).resolve().parents[4] / "scripts" / "feature_registry.json"
+
+        try:
+            registry = json.loads(registry_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            registry = {}
+
+        species = registry.get("hosts", {}).get(registry_key, {}).get("species")
+        return str(species or "Nicotiana benthamiana")
+
     def generate_run_id(self, sequence: str, params: dict[str, Any]) -> str:
         """
         Generate a reproducible run_id
@@ -69,6 +91,7 @@ class SequenceExporter:
                 "run_id": "abc12345",
                 "timestamp": "2026-01-22T12:00:00",
                 "organism": "Nicotiana benthamiana",
+                "host_profile": "nbenthamiana",
                 "gene_name": "GFP",
                 "violations_fixed": [...],
                 "warnings": [...]
@@ -99,7 +122,7 @@ class SequenceExporter:
         run_id = metadata.get("run_id", self.generate_run_id(sequence, metadata))
         timestamp = metadata.get("timestamp", datetime.now().strftime("%Y%m%d"))
         gene_name = metadata.get("gene_name", "optimized_gene")
-        organism = metadata.get("organism", "Nicotiana benthamiana")
+        organism = self.host_species(metadata)
 
         # Build locus ID
         locus_id = f"PFORM_{run_id}_{timestamp}"
@@ -355,7 +378,7 @@ class SequenceExporter:
             "--- Optimization Settings ---",
             f"Profile: {metadata.get('profile', 'N/A')}",
             f"Assembly Standard: {metadata.get('assembly_standard', 'None')}",
-            f"Organism: {metadata.get('organism', 'Nicotiana benthamiana')}",
+            f"Organism: {self.host_species(metadata)}",
             "",
         ]
 

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

@@ -17,7 +17,7 @@ class RuleBasedOptimizer(OptimizerEngine):
     """Profile-based rule optimization engine."""
 
     name = "Profile-based"
-    version = "3.1.7"
+    version = "3.1.8"
 
     def __init__(self) -> None:
         self.validator = InputValidator()

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

@@ -15,7 +15,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, cast
 
-from factorforge.engines.profile.scoring import calculate_composite_score
+from factorforge.engines.profile.scoring import GC_OPT_MID, calculate_composite_score
 from factorforge.engines.profile.utils import (
     build_aa_to_codons_map,
     calculate_gc,
@@ -440,14 +440,22 @@ class ReverseTranslator:
         return "".join(dna_seq)
 
     def _gc_target_translate(self, protein_seq: str, **kwargs: Any) -> str:
-        """
-        GC-Target profile: enforce GC% 42.5% ±2% (N. benthamiana optimal)
+        """GC-Target profile: drive global GC toward a configurable target.
+
+        Targets the caller-supplied ``target_gc`` if provided, otherwise the
+        host-profile GC midpoint (GC_OPT_MID = 60% for N. benthamiana). To target
+        a lower GC (e.g. for specific vector requirements), pass target_gc explicitly.
 
         - GC constraint first
         - CAI may be sacrificed
         - Balance local window GC (50 bp)
+
+        TODO: GC_OPT_MID is currently a single N. benthamiana-calibrated constant.
+        When per-host GC profiles are added, source the default from the active host.
         """
-        target_gc = kwargs.get("target_gc", 42.5)
+        target_gc = kwargs.get("target_gc")
+        if target_gc is None:
+            target_gc = GC_OPT_MID
 
         dna_seq: list[str] = []
 
@@ -477,11 +485,22 @@ class ReverseTranslator:
         return "".join(dna_seq)
 
     def _assembly_friendly_translate(self, protein_seq: str, **kwargs: Any) -> str:
-        """
-        Assembly-Friendly profile: avoid BsaI/BpiI
+        """Translate for Golden Gate / MoClo assembly compatibility.
+
+        Strategy:
+        - Starts from balanced codon selection (preferred_ratio=0.6)
+        - Retries up to max_attempts times until no BsaI/BpiI Type IIS
+          restriction sites remain in the CDS (forward + reverse complement)
+        - CAI trade-offs are accepted to achieve site-free sequences
 
-        - Golden Gate compatible
-        - CAI trade-offs allowed
+        Current scope:
+        - Supported: BsaI/BpiI site avoidance via stochastic retry
+        - Not yet implemented: local GC window uniformity scoring,
+          repeat-pattern penalties, synthesis vendor constraint profiles
+
+        Args:
+            protein_seq: Amino acid sequence.
+            max_attempts: Retry limit for site removal (default: 10).
         """
         max_attempts = kwargs.get("max_attempts", 10)
         if max_attempts < 1:
@@ -529,13 +548,18 @@ class ReverseTranslator:
         return self._apply_nterminal_ramp(dna_seq, protein_seq, ramp_codons=ramp_codons)
 
     def _apply_nterminal_ramp(self, dna_seq: str, protein_seq: str, ramp_codons: int = 50) -> str:
-        """
-        Apply N-terminal codon ramp for co-translational folding.
+        """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.
 
+        TODO: ramp profile is currently not in VALID_PROFILES (not publicly accessible).
+        Before re-enabling, revisit ramp_codons=50:
+        - Literature suggests 10–30 codons (Tuller et al. 2010, Chu et al. 2014).
+        - For short proteins, 50 codons can cover the entire CDS.
+        - Consider: ramp_len = min(30, max(10, int(protein_length * 0.15)))
+
         Args:
             dna_seq: Full-length DNA sequence.
             protein_seq: Original protein sequence (same length as dna_seq/3).

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

@@ -11,6 +11,7 @@ import math
 import re
 from typing import Any
 
+from factorforge.analysis.metrics import HOMOPOLYMER_SYNTHESIS_WARN_NT
 from factorforge.engines.profile.rules.reverse_translator import ReverseTranslator
 from factorforge.engines.profile.utils import (
     build_aa_to_codons_map,
@@ -246,24 +247,27 @@ class RuleEngine:
 
         return violations
 
-    def scan_homopolymers(self, seq: str, min_length: int = 8) -> list[dict[str, Any]]:
-        """
-        Detect 8+ homopolymers (synthesis risk)
+    def scan_homopolymers(
+        self, seq: str, min_length: int = HOMOPOLYMER_SYNTHESIS_WARN_NT
+    ) -> list[dict[str, Any]]:
+        """Detect homopolymer runs for synthesis/manufacturing risk evaluation.
 
-        Args:
-            seq: DNA sequence
-            min_length: Minimum length
+        Uses HOMOPOLYMER_SYNTHESIS_WARN_NT (default 8 nt) — the threshold at
+        which gene synthesis vendors flag homopolymers as difficult to synthesize
+        with high fidelity.
 
-        Returns:
-            List of violations
+        For expression stability risk (≥6 nt), see
+        factorforge.analysis.metrics.detect_homopolymers() which uses
+        HOMOPOLYMER_EXPRESSION_WARN_NT.
 
-        Raises:
-            None.
+        Args:
+            seq: DNA sequence
+            min_length: Minimum run length to flag (default: HOMOPOLYMER_SYNTHESIS_WARN_NT)
 
         Examples:
             >>> engine = RuleEngine()
             >>> engine.scan_homopolymers("AAAAAAAA", min_length=8)
-            [{'type': 'homopolymer', ...}]
+            [{'type': 'homopolymer', 'context': 'synthesis', ...}]
         """
         violations: list[dict[str, Any]] = []
 
@@ -280,16 +284,16 @@ class RuleEngine:
                 while idx + actual_length < len(seq) and seq[idx + actual_length] == base:
                     actual_length += 1
 
-                violations.append(
-                    {
-                        "type": "homopolymer",
-                        "base": base,
-                        "position": idx,
-                        "length": actual_length,
-                        "sequence": base * actual_length,
-                        "severity": "high" if actual_length >= 10 else "medium",
-                    }
-                )
+                violations.append({
+                    "type": "homopolymer",
+                    "context": "synthesis",
+                    "threshold_nt": min_length,
+                    "base": base,
+                    "position": idx,
+                    "length": actual_length,
+                    "sequence": base * actual_length,
+                    "severity": "high" if actual_length >= 10 else "medium",
+                })
                 pos = idx + actual_length
 
         return violations

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

@@ -11,13 +11,16 @@ from typing import Any
 
 logger = logging.getLogger(__name__)
 
-# Optimal GC range for N. benthamiana codon-optimized sequences.
+# GC band for N. benthamiana codon-optimized sequences.
 # Benchmark (analysis 004, n=49): balanced profile output average GC% = 60.1%
 # (range 55-71%). The genome-wide average (~42%) reflects all genes, not the
 # high-expression codon table which exhibits 3rd-position GC bias.
+# These constants define the acceptable band — sequences within [GC_OPT_MIN, GC_OPT_MAX]
+# receive full GC score; outside the band the score decays linearly.
 GC_OPT_MIN = 55.0
 GC_OPT_MAX = 65.0
-GC_OPT_MID = 60.0
+GC_OPT_MID = 60.0  # kept for gc_target point-scoring and viral_delivery centering
+GC_DECAY_WIDTH = 20.0  # percentage points outside band before score reaches 0.0
 
 # ViennaRNA availability cache
 _vienna_available: bool | None = None
@@ -32,7 +35,11 @@ class ScoringConfig:
     w_mfe: float = 0.2
     w_dinuc: float = 0.0  # CpG/TpA dinucleotide penalty (opt-in, default off)
     w_syncodonlm: float = 0.0  # SynCodonLM quality score (opt-in, default off)
-    gc_opt: float = GC_OPT_MID
+    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
+    gc_min: float = GC_OPT_MIN  # acceptable band lower boundary
+    gc_max: float = GC_OPT_MAX  # acceptable band upper boundary
+    gc_decay_width: float = GC_DECAY_WIDTH  # % points outside band before score → 0
     use_mfe: bool = True
 
     def __post_init__(self) -> None:
@@ -61,22 +68,28 @@ class ScoringConfig:
 
 # Pre-defined scoring configs per optimization profile
 PROFILE_SCORING_CONFIGS: dict[str, ScoringConfig] = {
-    "balanced": ScoringConfig(w_cai=0.5, w_gc=0.3, w_mfe=0.2, gc_opt=GC_OPT_MID),
-    "high_cai": ScoringConfig(w_cai=0.8, w_gc=0.1, w_mfe=0.1, gc_opt=GC_OPT_MID),
-    "gc_target": ScoringConfig(w_cai=0.1, w_gc=0.7, w_mfe=0.2, gc_opt=GC_OPT_MID),
-    "assembly_friendly": ScoringConfig(w_cai=0.5, w_gc=0.3, w_mfe=0.2, gc_opt=GC_OPT_MID),
-    "ramp": ScoringConfig(w_cai=0.4, w_gc=0.3, w_mfe=0.3, gc_opt=GC_OPT_MID),
-    # TRV viral-delivery profile — GC target ~47.5% based on TRV genome composition.
-    # MFE weighted at 0.30 (Peccoud et al. 2024, PMC11718241: secondary structure shows
-    # weak univariate correlation with yield in tobacco viral expression).
-    "viral_delivery": ScoringConfig(w_cai=0.35, w_gc=0.35, w_mfe=0.30, gc_opt=47.5, use_mfe=True),
-    "ml_enhanced": ScoringConfig(
-        w_cai=0.35,
-        w_gc=0.25,
-        w_mfe=0.15,
-        w_syncodonlm=0.25,
-        gc_opt=GC_OPT_MID,
+    "balanced": ScoringConfig(w_cai=0.5, w_gc=0.3, w_mfe=0.2),
+    # high_cai: CAI 1.0 mimics naturally high-expression N. benthamiana genes (golden_set).
+    # For very long or structurally complex proteins under extreme agroinfiltration overexpression,
+    # consider the ramp profile instead (N-terminal codon deoptimization reduces ribosome stalling).
+    "high_cai": ScoringConfig(w_cai=0.8, w_gc=0.1, w_mfe=0.1),
+    # gc_target: gc_min/gc_max are overridden dynamically from target_gc kwarg in
+    # calculate_composite_score — the config defaults here are not used for band scoring.
+    "gc_target": ScoringConfig(w_cai=0.1, w_gc=0.7, w_mfe=0.2),
+    # assembly_friendly: CAI pressure reduced vs balanced; GC/MFE weights raised to
+    # reflect Type IIS restriction-site avoidance priority (Golden Gate / MoClo).
+    # w_gc scores GC band compliance (global GC%), NOT local GC uniformity.
+    # Window-level GC variance and repeat-pattern penalties are not yet implemented.
+    "assembly_friendly": ScoringConfig(w_cai=0.3, w_gc=0.4, w_mfe=0.3),
+    "ramp": ScoringConfig(w_cai=0.4, w_gc=0.3, w_mfe=0.3),
+    # TRV viral-delivery profile — GC band centered on TRV genome composition (~47.5%).
+    # MFE weighted at 0.30 (Peccoud et al. 2024, PMC11718241).
+    "viral_delivery": ScoringConfig(
+        w_cai=0.35, w_gc=0.35, w_mfe=0.30,
+        gc_opt=47.5, gc_min=37.5, gc_max=57.5,
+        use_mfe=True,
     ),
+    "ml_enhanced": ScoringConfig(w_cai=0.35, w_gc=0.25, w_mfe=0.15, w_syncodonlm=0.25),
 }
 
 
@@ -144,6 +157,36 @@ def normalize_mfe(mfe: float, seq_length: int) -> float:
     return 1.0 + (clamped / 0.5)
 
 
+def gc_band_score(
+    gc: float,
+    gc_min: float,
+    gc_max: float,
+    decay_width: float = GC_DECAY_WIDTH,
+) -> float:
+    """Score GC content against an acceptable band.
+
+    Returns 1.0 inside [gc_min, gc_max]; linearly decays to 0.0 after
+    decay_width percentage points outside the band.
+
+    Args:
+        gc: GC content percentage (0-100).
+        gc_min: Lower boundary of acceptable band.
+        gc_max: Upper boundary of acceptable band.
+        decay_width: Percentage points outside band before score reaches 0.0.
+
+    Examples:
+        gc_min=55, gc_max=65, decay_width=20:
+          gc=60 → 1.00  (inside band)
+          gc=70 → 0.75  (5 pts above gc_max)
+          gc=80 → 0.25  (15 pts above gc_max)
+          gc=85 → 0.00  (20 pts above gc_max)
+    """
+    if gc_min <= gc <= gc_max:
+        return 1.0
+    distance = (gc_min - gc) if gc < gc_min else (gc - gc_max)
+    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).
 
@@ -179,19 +222,23 @@ def calculate_composite_score(
     profile: str | None = None,
     **kwargs: Any,
 ) -> float:
-    """
-    Calculate multidimensional composite score.
+    """Calculate multidimensional composite score.
 
-    S = w1*CAI + w2*(1 - |GC - GC_opt|/50) + w3*MFE_norm
+    S = w1*CAI + w2*gc_band_score + w3*MFE_norm
         + w4*dinuc_score + w5*SynCodonLM_score
 
+    GC scoring uses a band function: sequences inside [gc_min, gc_max] receive
+    full score (1.0); outside the band the score decays linearly to 0.0 over
+    gc_decay_width percentage points. For gc_target profile, the band is
+    centred on the caller-supplied target_gc (±5 pp).
+
     Args:
         cai: Codon Adaptation Index (0-1).
         gc: GC content percentage (0-100).
         sequence: DNA sequence for optional MFE, dinucleotide, and SynCodonLM calculation.
         config: Explicit ScoringConfig. Overrides profile.
         profile: Profile name for preset config lookup.
-        **kwargs: Additional parameters (e.g., target_gc for gc_target profile).
+        **kwargs: target_gc (float) — point target for gc_target profile.
 
     Returns:
         Composite score (0-1).
@@ -203,14 +250,17 @@ def calculate_composite_score(
         if config is None:
             config = PROFILE_SCORING_CONFIGS["balanced"]
 
-    # Allow target_gc override for gc_target profile
-    gc_opt = float(kwargs.get("target_gc", config.gc_opt))
-
     # Component 1: CAI (already 0-1)
     cai_score = max(0.0, min(1.0, cai))
 
-    # Component 2: GC proximity to optimum
-    gc_score = max(0.0, 1.0 - abs(gc - gc_opt) / 50.0)
+    # Component 2: GC band scoring
+    # gc_target profile: caller supplies target_gc; use a ±5 pp band around it.
+    # All other profiles: use the band defined in ScoringConfig (gc_min/gc_max).
+    if "target_gc" in kwargs:
+        tgt = float(kwargs["target_gc"])
+        gc_score = gc_band_score(gc, tgt - 5.0, tgt + 5.0, config.gc_decay_width)
+    else:
+        gc_score = gc_band_score(gc, config.gc_min, config.gc_max, config.gc_decay_width)
 
     # Component 3: MFE (optional)
     mfe_score = 0.5  # neutral default

{factorforge_cds-3.1.7 → factorforge_cds-3.1.8}/src/factorforge/utils/sequence_validator.py

@@ -2,7 +2,7 @@
 
 from typing import Literal, Tuple
 
-from factorforge.analysis.metrics import detect_invalid_codons, translate_dna
+from factorforge.analysis.metrics import amino_acid_identity, detect_invalid_codons, translate_dna
 
 from .exceptions import SequenceValidationError
 
@@ -186,4 +186,5 @@ def validate_cds_output(input_protein: str, dna_sequence: str) -> dict[str, obje
     return {
         "passed": not errors,
         "errors": errors,
+        "aa_identity": amino_acid_identity(expected, seq),
     }

{factorforge_cds-3.1.7 → factorforge_cds-3.1.8}/src/factorforge/utils/validation.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from factorforge.analysis.metrics import (
+    HOMOPOLYMER_EXPRESSION_WARN_NT,
     amino_acid_identity,
     calculate_first_region_gc,
     calculate_gc,
@@ -24,7 +25,8 @@ DEFAULT_CONFIG: dict[str, Any] = {
     "gc_window_step": 30,
     "forbidden_motifs": [],
     "fail_forbidden_motifs": False,
-    "homopolymer_max_run": 6,
+    # Expression-stability threshold (see HOMOPOLYMER_EXPRESSION_WARN_NT in metrics).
+    "homopolymer_max_run": HOMOPOLYMER_EXPRESSION_WARN_NT,
 }
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.1.7
+Version: 3.1.8
 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.7 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.1.8 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.1.7 → factorforge_cds-3.1.8}/tests/test_sequence_validator.py

@@ -66,7 +66,7 @@ def test_validate_protein_sequence():
 def test_validate_cds_output_passes_normal_cds():
     result = validate_cds_output("MAF", "ATGGCTTTC")
 
-    assert result == {"passed": True, "errors": []}
+    assert result == {"passed": True, "errors": [], "aa_identity": 1.0}
 
 
 def test_validate_cds_output_fails_internal_stop():
@@ -80,6 +80,7 @@ def test_validate_cds_output_fails_aa_mismatch():
     result = validate_cds_output("MAF", "ATGGCTTAC")
 
     assert result["passed"] is False
+    assert result["aa_identity"] == pytest.approx(2 / 3)
     assert any(error.startswith("aa_mismatch") for error in result["errors"])