factorforge-cds 3.2.8__tar.gz → 3.3.1__tar.gz

{factorforge_cds-3.2.8/src/factorforge_cds.egg-info → factorforge_cds-3.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.2.8
-Summary: FactorForge - open-source CDS design and pre-synthesis sequence review engine by Eijex.
+Version: 3.3.1
+Summary: FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex.
 Author-email: Eijex <eijex.lab@gmail.com>
 License-Expression: AGPL-3.0-only
 Project-URL: Homepage, https://factorforge.eijex.com
@@ -33,7 +33,7 @@ Dynamic: license-file
 
 # FactorForge
 
-**Open-source constraint-based CDS design and pre-synthesis sequence review engine for plant CDS workflows, with primary support for *Nicotiana benthamiana* (Tobacco BY-2: experimental).**
+**Open-source constraint-based CDS design and pre-synthesis sequence review for plant CDS workflows, with primary support for *Nicotiana benthamiana* (Tobacco BY-2: experimental).**
 
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
@@ -93,7 +93,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.2.8 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.3.1 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.2.8 → factorforge_cds-3.3.1}/README.md

@@ -1,6 +1,6 @@
 # FactorForge
 
-**Open-source constraint-based CDS design and pre-synthesis sequence review engine for plant CDS workflows, with primary support for *Nicotiana benthamiana* (Tobacco BY-2: experimental).**
+**Open-source constraint-based CDS design and pre-synthesis sequence review for plant CDS workflows, with primary support for *Nicotiana benthamiana* (Tobacco BY-2: experimental).**
 
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
@@ -60,7 +60,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.2.8 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.3.1 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.2.8 → factorforge_cds-3.3.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.2.8"
-description = "FactorForge - open-source CDS design and pre-synthesis sequence review engine by Eijex."
+version = "3.3.1"
+description = "FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"
 license-files = ["LICENSE"]
@@ -53,7 +53,7 @@ factorforge-validate = "factorforge.validation.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-"factorforge" = ["data/*.json", "data/templates/*.json", "schemas/*.json"]
+"factorforge" = ["data/*.json", "data/templates/*.json", "data/profiles/*.json", "data/reference/*.json", "schemas/*.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{factorforge_cds-3.2.8 → factorforge_cds-3.3.1}/src/factorforge/__init__.py

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

{factorforge_cds-3.2.8 → factorforge_cds-3.3.1}/src/factorforge/analysis/feasibility.py

@@ -14,19 +14,16 @@ from factorforge.analysis.metrics import (
 )
 
 
-# Defaults calibrated to nbenthamiana profile engine output distribution
-# (internal benchmark, n=49): avg CAI=0.76, avg GC=60.1% (range 55-71%).
-# DEFAULT_CAI_TARGET=0.82 aligns with industry practice (>0.8) and is achievable.
+# Defaults for the current N. benthamiana software-default codon reference.
+# DEFAULT_CAI_TARGET=0.82 remains a soft in-silico target aligned with
+# industry practice (>0.8). DEFAULT_GC_LOW/HIGH track the NbeV1.1
+# high-confidence CDS-derived native composition band. These are not wet-lab
+# validation, expression/yield prediction, or biological-superiority claims.
 # Exported as named constants so tests/test_registry_production_sync.py can
 # strictly compare them against the registry (single source of truth).
-#
-# DEFAULT_GC_LOW/HIGH provisionally reverted from the Job 168/v3.3.0
-# native-genome-composition anchor (40-47%, released as part of v3.2.7) back
-# to the legacy engine-output-calibrated band, pending an MFE re-sensitivity +
-# 2x2 factorial recheck. See scoring.py's GC_OPT_MIN/MAX comment.
 DEFAULT_CAI_TARGET: float = 0.82
-DEFAULT_GC_LOW: float = 55.0
-DEFAULT_GC_HIGH: float = 65.0
+DEFAULT_GC_LOW: float = 40.0
+DEFAULT_GC_HIGH: float = 47.0
 
 
 AA_TO_CODONS: dict[str, list[str]] = {}
@@ -121,7 +118,7 @@ def analyze_feasibility(
     if not protein:
         raise ValueError("protein_sequence must not be empty")
 
-    ranges = gc_ranges or [(55.0, 65.0), (50.0, 65.0), (40.0, 65.0)]
+    ranges = gc_ranges or [(40.0, 47.0), (40.0, 55.0), (40.0, 65.0)]
     normalized_ranges = [
         (_normalize_gc_bound(low), _normalize_gc_bound(high)) for low, high in ranges
     ]

{factorforge_cds-3.2.8 → factorforge_cds-3.3.1}/src/factorforge/analysis/metrics.py

@@ -98,7 +98,7 @@ class CodonUsageTable:
 
 
 def _default_codon_table_path() -> Path:
-    # Job 168 / v3.3.0 (_analysis/025): production default switched from the
+    # v3.3.0 reference-policy update: production default switched from the
     # legacy Kazusa/SGN-derived table to the NbeV1.1 LAB-strain high-confidence
     # derived table. See data/reference/active_codon_reference.json.
     return get_data_path() / "profiles" / "nbev11_cds_hc_derived_codons.json"

{factorforge_cds-3.2.8 → factorforge_cds-3.3.1}/src/factorforge/cli/main.py

@@ -8,15 +8,119 @@ Usage:
 """
 
 from pathlib import Path
+import hashlib
+import json
 import sys
 
 import click
 
 from factorforge import __version__
+from factorforge.analysis.feasibility import DEFAULT_CAI_TARGET
 from factorforge.engines.registry import EngineRegistry
 from factorforge.engines.profile.utils import parse_fasta_records
 
 HOST_MAP = {"nbenthamiana": "nbenthamiana", "by2": "ntabacum"}
+HOST_TAXIDS = {"nbenthamiana": 4100, "ntabacum": 4097}
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+FACTORFORGE_REPO_ROOT = Path(__file__).resolve().parents[3]
+REFERENCE_POLICY_MANIFEST_PATH = (
+    FACTORFORGE_REPO_ROOT / "data" / "reference" / "reference_policy_manifest.json"
+)
+BUNDLED_REFERENCE_POLICY_MANIFEST_PATH = (
+    PACKAGE_ROOT / "data" / "reference" / "reference_policy_manifest.json"
+)
+
+
+def _reference_policy_manifest_path() -> Path:
+    """Return the repo manifest during development, or the packaged manifest in wheels."""
+    if REFERENCE_POLICY_MANIFEST_PATH.exists():
+        return REFERENCE_POLICY_MANIFEST_PATH
+    return BUNDLED_REFERENCE_POLICY_MANIFEST_PATH
+
+
+def _resolve_packaged_or_repo_path(relative_path: str) -> Path:
+    """Resolve manifest paths in a source checkout or an installed wheel."""
+    repo_path = FACTORFORGE_REPO_ROOT / relative_path
+    if repo_path.exists():
+        return repo_path
+
+    package_prefix = "src/factorforge/"
+    if relative_path.startswith(package_prefix):
+        return PACKAGE_ROOT / relative_path.removeprefix(package_prefix)
+    return PACKAGE_ROOT / relative_path
+
+
+def _load_reference_policy_manifest() -> dict:
+    """Load the checksum/tier policy manifest for expert CLI reference selection."""
+    return json.loads(_reference_policy_manifest_path().read_text(encoding="utf-8"))
+
+
+def _reference_entries_by_id() -> dict[str, dict]:
+    manifest = _load_reference_policy_manifest()
+    return {entry["reference_id"]: entry for entry in manifest["references"]}
+
+
+def _reference_id_choices() -> tuple[str, ...]:
+    return tuple(_reference_entries_by_id())
+
+
+REFERENCE_ID_CHOICES = _reference_id_choices()
+
+
+def _reference_entry_by_id(reference_id: str) -> dict:
+    entries = _reference_entries_by_id()
+    try:
+        return entries[reference_id]
+    except KeyError as exc:
+        choices = ", ".join(sorted(entries))
+        raise click.UsageError(
+            f"Unknown reference_id {reference_id!r}. Supported values: {choices}"
+        ) from exc
+
+
+def _sha256_file(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def resolve_reference_by_id(reference_id: str) -> Path:
+    """Resolve a manifest reference_id to a checksum-verified codon table path."""
+    entry = _reference_entry_by_id(reference_id)
+    codon_table_path = _resolve_packaged_or_repo_path(str(entry["codon_table_path"]))
+    expected = str(entry["checksum_sha256"])
+    if not codon_table_path.exists():
+        raise click.UsageError(
+            f"Codon table file for {reference_id} does not exist: {codon_table_path}"
+        )
+    actual = _sha256_file(codon_table_path)
+    if actual != expected:
+        raise click.UsageError(
+            "Checksum mismatch for "
+            f"{reference_id} at {codon_table_path}: expected {expected}, actual {actual}"
+        )
+
+    if entry["tier"] != "production_enabled":
+        limitations = "; ".join(entry.get("known_limitations", []))
+        warning = (
+            f"Warning: reference_id={reference_id} has tier={entry['tier']}; "
+            f"{entry['claim_boundary']}"
+        )
+        if limitations:
+            warning = f"{warning} Known limitations: {limitations}"
+        click.echo(warning, err=True)
+
+    return codon_table_path
+
+
+def _validate_reference_host(reference_id: str, internal_host: str) -> None:
+    entry = _reference_entry_by_id(reference_id)
+    expected_taxid = HOST_TAXIDS[internal_host]
+    actual_taxid = int(entry["ncbi_taxid"])
+    if actual_taxid != expected_taxid:
+        raise click.UsageError(
+            f"reference_id={reference_id} targets {entry['organism']} "
+            f"(NCBI taxid {actual_taxid}) and is incompatible with "
+            f"--host {internal_host} (expected NCBI taxid {expected_taxid})."
+        )
 
 
 def _configure_stdio() -> None:
@@ -43,7 +147,14 @@ def _wrap_sequence(sequence, width=80):
     return "\n".join(sequence[i : i + width] for i in range(0, len(sequence), width))
 
 
-def _build_dp_result(sequence: str, objective: str, gc_min: float, gc_max: float):
+def _build_dp_result(
+    sequence: str,
+    objective: str,
+    gc_min: float,
+    gc_max: float,
+    cai_target: float = DEFAULT_CAI_TARGET,
+    codon_table_path: Path | None = None,
+):
     """Run the constraint-based DP feasibility engine for a single protein sequence."""
     if objective != "feasibility_best":
         raise ValueError("DP engine currently supports --objective feasibility_best.")
@@ -53,10 +164,11 @@ def _build_dp_result(sequence: str, objective: str, gc_min: float, gc_max: float
     from factorforge.analysis.metrics import load_codon_usage_table
     from factorforge.analysis.feasibility import analyze_feasibility
 
-    table = load_codon_usage_table()
+    table = load_codon_usage_table(path=codon_table_path)
     result = analyze_feasibility(
         sequence,
         table.codon_weights,
+        target_cai=cai_target,
         target_gc_low=gc_min,
         target_gc_high=gc_max,
     )
@@ -75,9 +187,17 @@ def _build_dp_result(sequence: str, objective: str, gc_min: float, gc_max: float
     return best, result, reason
 
 
-def _format_dp_fasta(sequence_id: str, dna_sequence: str, cai: float, gc: float) -> str:
+def _format_dp_fasta(
+    sequence_id: str,
+    dna_sequence: str,
+    cai: float,
+    gc: float,
+    requested_cai_target: float | None = None,
+) -> str:
     """Format a DP result as FASTA."""
     header = f">{sequence_id}|engine=dp|objective=feasibility_best|cai={cai:.3f}|gc={gc:.2f}"
+    if requested_cai_target is not None:
+        header = f"{header}|target_cai={requested_cai_target:.3f}"
     return f"{header}\n{_wrap_sequence(dna_sequence)}\n"
 
 
@@ -106,6 +226,12 @@ def _format_profile_fasta(sequence_id: str, profile: str, result) -> str:
     return f"{header}\n{_wrap_sequence(result.sequence)}\n"
 
 
+def _single_profile_sequence_id(input_file: str, fasta_records) -> str:
+    if fasta_records is not None and len(fasta_records) == 1:
+        return str(fasta_records[0][0])
+    return Path(input_file).stem or "factorforge_profile"
+
+
 def _format_profile_comparison_table(profile_results) -> str:
     """Format profile optimization metrics as a comparison table."""
     divider = "─" * 45
@@ -164,11 +290,23 @@ def list_engines():
     type=click.Choice(["feasibility_best"], case_sensitive=False),
     help="DP objective",
 )
-@click.option("--gc-min", type=float, default=55.0, help="Minimum target GC percentage")
-@click.option("--gc-max", type=float, default=65.0, help="Maximum target GC percentage")
+@click.option("--gc-min", type=float, default=40.0, help="Minimum target GC percentage")
+@click.option("--gc-max", type=float, default=47.0, help="Maximum target GC percentage")
+@click.option(
+    "--cai-target",
+    type=float,
+    default=DEFAULT_CAI_TARGET,
+    help="Requested DP target CAI threshold",
+)
 @click.option("--template", "construct_template", help="Construct template name")
 @click.option("--output", "-o", help="Output file")
 @click.option("--format", "output_format", default="fasta", help="Output format (fasta, genbank)")
+@click.option(
+    "--reference-id",
+    type=click.Choice(REFERENCE_ID_CHOICES, case_sensitive=False),
+    default=None,
+    help="Expert/research codon-reference ID; checksum-validated.",
+)
 @click.option(
     "--compare-profiles",
     help=(
@@ -192,9 +330,11 @@ def optimize(
     objective,
     gc_min,
     gc_max,
+    cai_target,
     construct_template,
     output,
     output_format,
+    reference_id,
     compare_profiles,
     scan_mode,
     scan_include,
@@ -206,6 +346,12 @@ def optimize(
     host_value = host.lower()
     internal_host = HOST_MAP[host_value]
     host_was_explicit = _option_was_explicitly_set("host")
+    reference_id = reference_id.lower() if reference_id else None
+    reference_table_path = None
+
+    if reference_id is not None:
+        _validate_reference_host(reference_id, internal_host)
+        reference_table_path = resolve_reference_by_id(reference_id)
 
     if host_was_explicit and engine == "dp" and _engine_option_was_explicitly_set():
         raise click.UsageError("--host is only supported with --engine profile")
@@ -224,6 +370,9 @@ def optimize(
             raise click.UsageError("--compare-profiles cannot be used with --engine dp.")
         engine = "profile"
 
+    if reference_table_path is not None and construct_template:
+        raise click.UsageError("--reference-id is not supported with --template mode.")
+
     try:
         # Read file
         with open(input_file, encoding="utf-8") as f:
@@ -247,7 +396,12 @@ def optimize(
             if output_format.lower() != "fasta":
                 raise ValueError("Profile comparison only supports FASTA output.")
 
-            optimizer = EngineRegistry.get("profile")
+            if reference_table_path is not None:
+                from factorforge.engines.profile.optimizer import RuleBasedOptimizer
+
+                optimizer = RuleBasedOptimizer(codon_table_path=str(reference_table_path))
+            else:
+                optimizer = EngineRegistry.get("profile")
             profile_results = []
             for profile_name in compare_profile_list:
                 result = optimizer.optimize(
@@ -279,7 +433,12 @@ def optimize(
             if output_format.lower() != "fasta":
                 raise ValueError("Multi-FASTA input only supports FASTA output.")
 
-            optimizer = EngineRegistry.get(engine)
+            if reference_table_path is not None and engine == "profile":
+                from factorforge.engines.profile.optimizer import RuleBasedOptimizer
+
+                optimizer = RuleBasedOptimizer(codon_table_path=str(reference_table_path))
+            else:
+                optimizer = EngineRegistry.get(engine)
             payload = [{"id": seq_id, "sequence": seq} for seq_id, seq in fasta_records]
             if hasattr(optimizer, "optimize_batch"):
                 results = optimizer.optimize_batch(
@@ -336,12 +495,21 @@ def optimize(
                 objective=objective,
                 gc_min=gc_min,
                 gc_max=gc_max,
+                cai_target=cai_target,
+                codon_table_path=reference_table_path,
             )
             dna_sequence = best["dna_sequence"]
             cai = float(best["cai"])
             gc = float(best["gc"])
             sequence_id = Path(input_file).stem or "factorforge_dp"
-            fasta = _format_dp_fasta(sequence_id, dna_sequence, cai, gc)
+            requested_cai_target = cai_target if _option_was_explicitly_set("cai_target") else None
+            fasta = _format_dp_fasta(
+                sequence_id,
+                dna_sequence,
+                cai,
+                gc,
+                requested_cai_target=requested_cai_target,
+            )
 
             click.echo("Optimizing with DP feasibility engine...")
             if output:
@@ -356,6 +524,8 @@ def optimize(
             click.echo(f"  - gc_percent: {gc:.2f}")
             click.echo(f"  - target_gc_min: {float(feasibility['target']['gc_low']):.2f}")
             click.echo(f"  - target_gc_max: {float(feasibility['target']['gc_high']):.2f}")
+            if requested_cai_target is not None:
+                click.echo(f"  - target_cai: {float(feasibility['target']['cai']):.3f}")
             click.echo(f"  - target_feasible: {bool(feasibility['target']['best_candidate'])}")
             click.echo(f"  - recommendation_reason: {recommendation_reason}")
             return
@@ -393,7 +563,12 @@ def optimize(
                 raise ValueError("Non-FASTA output requires --template with profile pipeline.")
 
             # Get engine
-            optimizer = EngineRegistry.get(engine)
+            if reference_table_path is not None and engine == "profile":
+                from factorforge.engines.profile.optimizer import RuleBasedOptimizer
+
+                optimizer = RuleBasedOptimizer(codon_table_path=str(reference_table_path))
+            else:
+                optimizer = EngineRegistry.get(engine)
 
             # Optimize
             click.echo(f"Optimizing with {optimizer.name} v{optimizer.version}...")
@@ -408,8 +583,10 @@ def optimize(
 
             # Output results
             if output:
+                sequence_id = _single_profile_sequence_id(input_file, fasta_records)
+                fasta = _format_profile_fasta(sequence_id, profile, result)
                 with open(output, "w", encoding="utf-8") as f:
-                    f.write(result.sequence)
+                    f.write(fasta)
                 click.echo(f"Saved to: {output}")
             else:
                 click.echo(f"\n{result.sequence}\n")