factorforge-cds 3.3.0__tar.gz → 3.3.2__tar.gz

{factorforge_cds-3.3.0 → factorforge_cds-3.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.3.0
+Version: 3.3.2
 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
@@ -93,7 +93,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.3.0 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.3.2 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.3.0 → factorforge_cds-3.3.2}/README.md

@@ -60,7 +60,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.3.0 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.3.2 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.3.0 → factorforge_cds-3.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.3.0"
+version = "3.3.2"
 description = "FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -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.3.0 → factorforge_cds-3.3.2}/src/factorforge/__init__.py

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

{factorforge_cds-3.3.0 → factorforge_cds-3.3.2}/src/factorforge/analysis/feasibility.py

@@ -51,6 +51,7 @@ def _cai_from_log(log_sum: float, codon_count: int) -> float:
 def _candidate_summary(
     dna_sequence: str | None,
     codon_weights: dict[str, float],
+    cai_authority: dict[str, Any],
 ) -> dict[str, Any] | None:
     if dna_sequence is None:
         return None
@@ -59,6 +60,7 @@ def _candidate_summary(
     return {
         "dna_sequence": dna_sequence,
         "cai": calculate_cai(dna_sequence, codon_weights),
+        "cai_authority": dict(cai_authority),
         "gc": calculate_gc(dna_sequence),
         "first_region_gc": calculate_first_region_gc(dna_sequence),
         "gc_window_min": min(window_values) if window_values else 0.0,
@@ -66,6 +68,20 @@ def _candidate_summary(
     }
 
 
+def _build_cai_authority(codon_reference_id: str | None) -> dict[str, Any]:
+    if codon_reference_id is None:
+        return {
+            "reference_id": None,
+            "reference_role": "cai_evaluation",
+            "reference_relationship": "unresolved",
+        }
+    return {
+        "reference_id": codon_reference_id,
+        "reference_role": "cai_evaluation",
+        "reference_relationship": "same_as_generation_reference",
+    }
+
+
 def _best_gc_under_gc_range(
     states: dict[int, float],
     protein_length: int,
@@ -104,6 +120,7 @@ def analyze_feasibility(
     target_gc_low: float = DEFAULT_GC_LOW,
     target_gc_high: float = DEFAULT_GC_HIGH,
     gc_ranges: list[tuple[float, float]] | None = None,
+    codon_reference_id: str | None = None,
 ) -> dict[str, Any]:
     """Compute exact CAI/GC feasibility over synonymous codon choices.
 
@@ -160,6 +177,7 @@ def analyze_feasibility(
 
     protein_length = len(protein)
     total_bases = protein_length * 3
+    cai_authority = _build_cai_authority(codon_reference_id)
     best_any_gc = max(states, key=lambda gc_count: states[gc_count])
     best_any_log_sum = states[best_any_gc]
     best_any_sequence = _reconstruct_sequence(backrefs, best_any_gc)
@@ -180,7 +198,7 @@ def analyze_feasibility(
             range_results[key] = {
                 "feasible": True,
                 "max_cai": _cai_from_log(states[gc_count], protein_length),
-                "best_candidate": _candidate_summary(sequence, codon_weights),
+                "best_candidate": _candidate_summary(sequence, codon_weights, cai_authority),
             }
 
     target_cai_possible = (
@@ -192,8 +210,13 @@ def analyze_feasibility(
         "protein_length": protein_length,
         "minimum_possible_gc": (min_gc_count / total_bases) * 100.0,
         "maximum_possible_gc": (max_gc_count / total_bases) * 100.0,
+        "cai_authority": dict(cai_authority),
         "maximum_achievable_cai_without_gc": _cai_from_log(best_any_log_sum, protein_length),
-        "best_candidate_without_gc": _candidate_summary(best_any_sequence, codon_weights),
+        "best_candidate_without_gc": _candidate_summary(
+            best_any_sequence,
+            codon_weights,
+            cai_authority,
+        ),
         "ranges": range_results,
         "target": {
             "cai": target_cai,
@@ -206,7 +229,11 @@ def analyze_feasibility(
                 else None
             ),
             "best_candidate": (
-                _candidate_summary(_reconstruct_sequence(backrefs, target_gc_count), codon_weights)
+                _candidate_summary(
+                    _reconstruct_sequence(backrefs, target_gc_count),
+                    codon_weights,
+                    cai_authority,
+                )
                 if target_gc_count is not None
                 else None
             ),

{factorforge_cds-3.3.0 → factorforge_cds-3.3.2}/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,15 @@ 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,
+    codon_reference_id: str | 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,12 +165,14 @@ 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,
+        codon_reference_id=codon_reference_id,
     )
     best = result["target"]["best_candidate"]
     feasible = best is not None
@@ -75,9 +189,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"
 
 
@@ -102,10 +224,19 @@ def _format_profile_fasta(sequence_id: str, profile: str, result) -> str:
     cai = float(result.metrics.get("cai", 0.0))
     gc = float(result.metrics.get("gc_percent", result.metrics.get("gc_content", 0.0)))
     score = float(result.metrics.get("score", 0.0))
-    header = f">{sequence_id}|profile={profile}|cai={cai:.3f}|gc={gc:.2f}|score={score:.3f}"
+    header = (
+        f">{sequence_id}|engine=profile|profile={profile}|"
+        f"cai={cai:.3f}|gc={gc:.2f}|score={score:.3f}"
+    )
     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
@@ -166,9 +297,21 @@ def list_engines():
 )
 @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 +335,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 +351,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 +375,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 +401,15 @@ 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),
+                    generation_reference_id=reference_id,
+                )
+            else:
+                optimizer = EngineRegistry.get("profile")
             profile_results = []
             for profile_name in compare_profile_list:
                 result = optimizer.optimize(
@@ -279,7 +441,15 @@ 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),
+                    generation_reference_id=reference_id,
+                )
+            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(
@@ -306,14 +476,9 @@ def optimize(
             combined_fasta = []
             for idx, result in enumerate(results):
                 seq_id = payload[idx]["id"]
-                cai = result.metrics.get("cai", 0.0)
-                gc = result.metrics.get("gc_percent", result.metrics.get("gc_content", 0.0))
-                score = result.metrics.get("score", 0.0)
-                header = (
-                    f">{seq_id}|profile={profile}|cai={float(cai):.3f}|"
-                    f"gc={float(gc):.2f}|score={float(score):.3f}"
+                combined_fasta.append(
+                    _format_profile_fasta(seq_id, profile, result).rstrip()
                 )
-                combined_fasta.append(f"{header}\n{_wrap_sequence(result.sequence)}")
             out_content = "\n".join(combined_fasta) + "\n"
 
             if output:
@@ -336,12 +501,22 @@ def optimize(
                 objective=objective,
                 gc_min=gc_min,
                 gc_max=gc_max,
+                cai_target=cai_target,
+                codon_table_path=reference_table_path,
+                codon_reference_id=reference_id,
             )
             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 +531,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 +570,15 @@ 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),
+                    generation_reference_id=reference_id,
+                )
+            else:
+                optimizer = EngineRegistry.get(engine)
 
             # Optimize
             click.echo(f"Optimizing with {optimizer.name} v{optimizer.version}...")
@@ -408,8 +593,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")

{factorforge_cds-3.3.0 → factorforge_cds-3.3.2}/src/factorforge/core/interfaces/optimizer.py

@@ -16,7 +16,7 @@ class OptimizationResult:
     def __init__(
         self,
         sequence: str,
-        metrics: dict[str, float],
+        metrics: dict[str, Any],
         metadata: dict[str, Any] | None = None,
     ) -> None:
         self.sequence = sequence

{factorforge_cds-3.3.0 → factorforge_cds-3.3.2}/src/factorforge/data/nbenthamiana_golden_set.json

@@ -1,6 +1,10 @@
 {
     "organism": "Nicotiana benthamiana",
+    "reference_id": "nbenthamiana_golden_set_v1",
+    "reference_role": "cai_evaluation",
+    "reference_version": "1",
     "source": "N. benthamiana high-expression CDS frequencies (70%, Kazusa CodonUsage DB / NCBI) blended with RNA-seq expression-weighted codon frequencies (30%, Grosse-Holz et al. 2018 Plant Biotechnology Journal; Prudhomme et al. 2024 Plant Biotechnology Journal / PRIDE PXD042916)",
+    "source_basis": "N. benthamiana high-expression CDS frequencies (70%, Kazusa CodonUsage DB / NCBI) blended with RNA-seq expression-weighted codon frequencies (30%, Grosse-Holz et al. 2018 Plant Biotechnology Journal; Prudhomme et al. 2024 Plant Biotechnology Journal / PRIDE PXD042916)",
     "description": "Codon usage frequencies weighted toward highly expressed N. benthamiana genes (RuBisCO, ribosomal proteins, histones). Used as CAI reference weights per Sharp & Li (1987). All source data is publicly available.",
     "blend_ratio": 0.7,
     "optimal_gc_content": 42.5,