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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.1.9
+Version: 3.2.1
 Summary: FactorForge - open-source constraint-based CDS design engine by Eijex.
 Author-email: Eijex <eijex.lab@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -20,6 +20,8 @@ Requires-Dist: requests>=2.31
 Requires-Dist: click>=8.0
 Requires-Dist: pydantic>=2.0
 Provides-Extra: dev
+Requires-Dist: jsonschema>=4.0; extra == "dev"
+Requires-Dist: pandas>=2.0; extra == "dev"
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: ruff>=0.1; extra == "dev"
@@ -31,17 +33,17 @@ Dynamic: license-file
 
 # FactorForge
 
-**Open-source constraint-based CDS design engine for plant expression workflows, with initial focus on *Nicotiana benthamiana* and Tobacco BY-2.**
+**Open-source constraint-based CDS design engine for sequence-level CDS design, 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/)
 [![PyPI](https://img.shields.io/pypi/v/factorforge-cds.svg)](https://pypi.org/project/factorforge-cds/)
 [![CI](https://github.com/eijex/factorforge-cds/actions/workflows/ci.yml/badge.svg)](https://github.com/eijex/factorforge-cds/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/eijex/factorforge-cds/branch/main/graph/badge.svg)](https://codecov.io/gh/eijex/factorforge-cds)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20407331.svg)](https://doi.org/10.5281/zenodo.20407331)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20640931.svg)](https://doi.org/10.5281/zenodo.20640931)
 [![Web App](https://img.shields.io/badge/web-factorforge.eijex.com-brightgreen.svg)](https://factorforge.eijex.com)
 
-FactorForge optimizes protein sequences into host-compatible CDS by maximizing CAI, controlling GC content, eliminating PolyA signals, and producing MoClo/Golden Gate-ready constructs. Supports *N. benthamiana* (agroinfiltration) and Tobacco BY-2 (`--host by2`, bioreactor/cGMP workflows).
+FactorForge performs profile-guided CDS design with CAI/GC metrics, PolyA-signal screening, and Golden Gate/MoClo-aware checks. Primary support: *N. benthamiana* (agroinfiltration). Experimental host context: Tobacco BY-2 (`--host by2`).
 
 **→ [Full Documentation](https://eijex.github.io/factorforge-cds/)**
 
@@ -65,7 +67,7 @@ Or use the **[web app](https://factorforge.eijex.com)** — no installation requ
 | **Web App** | No installation, demo & light use | [factorforge.eijex.com](https://factorforge.eijex.com) |
 | **CLI / Python** | Local use, batch processing, data privacy | `pip install factorforge-cds` |
 | **Docker** | Full web interface locally | `docker pull ghcr.io/eijex/factorforge-cds:latest` |
-| **Eijex MCP** | AI agent access (Claude Code, Cursor) | [mcp.eijex.com](https://mcp.eijex.com) |
+| **Eijex MCP** | MCP-compatible agent access | [mcp.eijex.com](https://mcp.eijex.com) |
 
 ---
 
@@ -82,59 +84,38 @@ and are not imported by the installed package or exposed as supported engines.
 
 ---
 
-## Development History
-
-FactorForge has gone through several implementation generations before the current public release:
-
-| Generation | Status | Description |
-|-----------|--------|-------------|
-| **v1** — NBent_OptiCodon | Internal | Thesis-derived codon optimization baseline for *N. benthamiana* |
-| **v2** — Rule-Based Engine | Internal → Production | Deterministic, constraint-aware design engine; became the foundation for the public release |
-| **v3-alpha** — ML Prototype | Archived | ML-based design attempt; performance was insufficient for production use; preserved under `archive/v3-ml-prototype/` |
-| **v3.0+** — Current release | Public | Open-source release of the matured v2 engine under `factorforge.engines.profile` |
-| **v3.7+** — ML Engine | Planned | ML-based design as `--engine ml`; added once sufficient wet-lab data is available |
-
-The `archive/` directory preserves all three earlier tracks for provenance. None are installed or exposed by the current package.
-
----
-
 ## ⚠️ Validation Status
 
-FactorForge predictions are **in-silico only** and have not been experimentally validated in wet-lab conditions. See [Validation](https://eijex.github.io/factorforge-cds/validation/) and [VALIDATION.md](VALIDATION.md).
+FactorForge outputs are **in-silico only** and have not been experimentally validated in wet-lab conditions. See [Validation](https://eijex.github.io/factorforge-cds/validation/) and [VALIDATION.md](VALIDATION.md).
 
 ---
 
 ## Citing
 
 ```
-FactorForge v3.1.9 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.2.0 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 
-*A citable publication is in preparation.*
-
 ---
 
-## Contributors
+## Maintainer
 
-| | Name | Role |
-|--|------|------|
-| 👤 | Mun-Kyu Kim ([@eijex](https://github.com/eijex)) | Author & maintainer |
-| 🤖 | Claude (Anthropic) | Design, analysis, planning |
-| 🤖 | Codex (OpenAI) | Implementation |
+Mun-Kyu Kim ([@eijex](https://github.com/eijex))
 
 ## License
 
 GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
 
-**Disclaimer:** FactorForge is provided for research purposes only. Predictions are computational and have not been experimentally validated.
+**Disclaimer:** FactorForge is provided for research purposes only. Outputs are computational and have not been experimentally validated.
 
 ---
 
 ## Get in Touch
 
 - **Docs** — [eijex.github.io/factorforge-cds](https://eijex.github.io/factorforge-cds/)
-- **Wet-lab Results** — [Submit via Google Form](https://docs.google.com/forms/d/e/1FAIpQLSeSx-wYvF6YwHhSPdLMl-L44frCugdm25X_eDz50OaqTD66qA/viewform?usp=header) (recommended) or [GitHub Issue](https://github.com/eijex/factorforge-cds/issues/new?template=wet_lab_result.yml)
+- **Wet-lab Results** — Public-safe validation summaries are welcome. [Share Wet-lab Results (Form)](https://docs.google.com/forms/d/e/1FAIpQLSeSx-wYvF6YwHhSPdLMl-L44frCugdm25X_eDz50OaqTD66qA/viewform) or [Share Wet-lab Results (GitHub)](https://github.com/eijex/factorforge-cds/issues/new?template=wet_lab_result.yml) (public-safe summaries only). Do not submit raw sequences, confidential construct details, internal batch IDs, patient data, private contact information, exact process parameters, or confidential partner/customer data. See [VALIDATION.md](VALIDATION.md) before submitting.
 - **GitHub Issues** — bugs, features: [github.com/eijex/factorforge-cds/issues](https://github.com/eijex/factorforge-cds/issues)
 - **Email** — eijex.lab@gmail.com
-- **Web** — [factorforge.eijex.com](https://factorforge.eijex.com)
+- **FactorForge** — [factorforge.eijex.com](https://factorforge.eijex.com)
+- **Lab** — [www.eijex.com](https://www.eijex.com)

factorforge_cds-3.2.1/README.md

@@ -0,0 +1,88 @@
+# FactorForge
+
+**Open-source constraint-based CDS design engine for sequence-level CDS design, 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/)
+[![PyPI](https://img.shields.io/pypi/v/factorforge-cds.svg)](https://pypi.org/project/factorforge-cds/)
+[![CI](https://github.com/eijex/factorforge-cds/actions/workflows/ci.yml/badge.svg)](https://github.com/eijex/factorforge-cds/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/eijex/factorforge-cds/branch/main/graph/badge.svg)](https://codecov.io/gh/eijex/factorforge-cds)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20640931.svg)](https://doi.org/10.5281/zenodo.20640931)
+[![Web App](https://img.shields.io/badge/web-factorforge.eijex.com-brightgreen.svg)](https://factorforge.eijex.com)
+
+FactorForge performs profile-guided CDS design with CAI/GC metrics, PolyA-signal screening, and Golden Gate/MoClo-aware checks. Primary support: *N. benthamiana* (agroinfiltration). Experimental host context: Tobacco BY-2 (`--host by2`).
+
+**→ [Full Documentation](https://eijex.github.io/factorforge-cds/)**
+
+---
+
+## Quick Start
+
+```bash
+pip install factorforge-cds
+factorforge optimize my_protein.fasta -o output.fasta
+```
+
+Or use the **[web app](https://factorforge.eijex.com)** — no installation required.
+
+---
+
+## Access Options
+
+| Method | Description | Link |
+|--------|-------------|------|
+| **Web App** | No installation, demo & light use | [factorforge.eijex.com](https://factorforge.eijex.com) |
+| **CLI / Python** | Local use, batch processing, data privacy | `pip install factorforge-cds` |
+| **Docker** | Full web interface locally | `docker pull ghcr.io/eijex/factorforge-cds:latest` |
+| **Eijex MCP** | MCP-compatible agent access | [mcp.eijex.com](https://mcp.eijex.com) |
+
+---
+
+## Repository Structure
+
+The supported production engine is the deterministic profile engine under:
+
+```text
+src/factorforge/engines/profile/
+```
+
+Historical implementation tracks are preserved under `archive/` for provenance
+and are not imported by the installed package or exposed as supported engines.
+
+---
+
+## ⚠️ Validation Status
+
+FactorForge outputs are **in-silico only** and have not been experimentally validated in wet-lab conditions. See [Validation](https://eijex.github.io/factorforge-cds/validation/) and [VALIDATION.md](VALIDATION.md).
+
+---
+
+## Citing
+
+```
+FactorForge v3.2.0 (2026). Open-source constraint-based CDS design engine.
+Eijex. https://github.com/eijex/factorforge-cds
+```
+
+---
+
+## Maintainer
+
+Mun-Kyu Kim ([@eijex](https://github.com/eijex))
+
+## License
+
+GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
+
+**Disclaimer:** FactorForge is provided for research purposes only. Outputs are computational and have not been experimentally validated.
+
+---
+
+## Get in Touch
+
+- **Docs** — [eijex.github.io/factorforge-cds](https://eijex.github.io/factorforge-cds/)
+- **Wet-lab Results** — Public-safe validation summaries are welcome. [Share Wet-lab Results (Form)](https://docs.google.com/forms/d/e/1FAIpQLSeSx-wYvF6YwHhSPdLMl-L44frCugdm25X_eDz50OaqTD66qA/viewform) or [Share Wet-lab Results (GitHub)](https://github.com/eijex/factorforge-cds/issues/new?template=wet_lab_result.yml) (public-safe summaries only). Do not submit raw sequences, confidential construct details, internal batch IDs, patient data, private contact information, exact process parameters, or confidential partner/customer data. See [VALIDATION.md](VALIDATION.md) before submitting.
+- **GitHub Issues** — bugs, features: [github.com/eijex/factorforge-cds/issues](https://github.com/eijex/factorforge-cds/issues)
+- **Email** — eijex.lab@gmail.com
+- **FactorForge** — [factorforge.eijex.com](https://factorforge.eijex.com)
+- **Lab** — [www.eijex.com](https://www.eijex.com)

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.1.9"
+version = "3.2.1"
 description = "FactorForge - open-source constraint-based CDS design engine by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -28,6 +28,8 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
+    "jsonschema>=4.0",
+    "pandas>=2.0",
     "pytest>=7.0",
     "pytest-cov>=4.0",
     "ruff>=0.1",

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

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

{factorforge_cds-3.1.9 → factorforge_cds-3.2.1}/src/factorforge/analysis/feasibility.py

@@ -14,6 +14,16 @@ from factorforge.analysis.metrics import (
 )
 
 
+# Defaults calibrated to nbenthamiana profile engine output distribution
+# (analysis 004, 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.
+# Exported as named constants so tests/test_registry_production_sync.py can
+# strictly compare them against the registry (single source of truth).
+DEFAULT_CAI_TARGET: float = 0.82
+DEFAULT_GC_LOW: float = 55.0
+DEFAULT_GC_HIGH: float = 65.0
+
+
 AA_TO_CODONS: dict[str, list[str]] = {}
 for _codon, _aa in STANDARD_GENETIC_CODE.items():
     if _aa == "*":
@@ -88,9 +98,9 @@ def _reconstruct_sequence(
 def analyze_feasibility(
     protein_sequence: str,
     codon_weights: dict[str, float],
-    target_cai: float = 0.82,
-    target_gc_low: float = 55.0,
-    target_gc_high: float = 65.0,
+    target_cai: float = DEFAULT_CAI_TARGET,
+    target_gc_low: float = DEFAULT_GC_LOW,
+    target_gc_high: float = DEFAULT_GC_HIGH,
     gc_ranges: list[tuple[float, float]] | None = None,
 ) -> dict[str, Any]:
     """Compute exact CAI/GC feasibility over synonymous codon choices.
@@ -99,9 +109,8 @@ def analyze_feasibility(
     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.
+    See module-level DEFAULT_CAI_TARGET / DEFAULT_GC_LOW / DEFAULT_GC_HIGH for
+    the calibration rationale (analysis 004, n=49).
     """
     protein = "".join(protein_sequence.upper().split()).rstrip("*")
     if not protein:

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

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

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

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

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

@@ -17,7 +17,7 @@ class RuleBasedOptimizer(OptimizerEngine):
     """Profile-based rule optimization engine."""
 
     name = "Profile-based"
-    version = "3.1.9"
+    version = "3.2.0"
 
     def __init__(self) -> None:
         self.validator = InputValidator()
@@ -30,6 +30,7 @@ class RuleBasedOptimizer(OptimizerEngine):
         sequence: str,
         profile: str | None = "balanced",
         host: str = "nbenthamiana",
+        seed: int | None = None,
         **kwargs: Any,
     ) -> OptimizationResult:
         """
@@ -91,7 +92,7 @@ class RuleBasedOptimizer(OptimizerEngine):
             candidates = [{"sequence": optimized_dna, "cai": cai, "gc": gc, "score": score}]
         else:
             candidates = translator.generate_candidates(
-                processed_seq, profile=opt_profile, n=1
+                processed_seq, profile=opt_profile, n=1, seed=seed
             )
             if not candidates:
                 raise ValueError("No candidates generated for input sequence.")

{factorforge_cds-3.1.9 → factorforge_cds-3.2.1}/src/factorforge/engines/profile/rules/domesticator.py

@@ -20,6 +20,18 @@ class Domesticator:
     - BioBricks (EcoRI, XbaI, SpeI, PstI)
     """
 
+    # Canonical Golden Gate Type IIS enzyme set, exported as GOLDEN_GATE_ENZYMES
+    # so tests/test_registry_production_sync.py::test_type_iis_sync can strictly
+    # compare it against the registry (single source of truth) instead of warning.
+    #
+    # BpiI and BbsI share the same GAAGAC Type IIS recognition/cut behavior in
+    # FactorForge's Golden Gate scanning context. The existing FactorForge
+    # production code and documentation consistently use BpiI as the canonical
+    # label; BbsI is a common synonym/vendor naming convention for the same
+    # scanning target. This is a naming normalization, not a biological
+    # threshold change. Order matches the registry value for stable comparison.
+    GOLDEN_GATE_ENZYMES: tuple[str, ...] = ("BsaI", "BpiI", "BsmBI")
+
     # Assembly standard definitions
     ASSEMBLY_STANDARDS: dict[str, dict[str, Any]] = {
         "golden_gate": {

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

@@ -423,7 +423,7 @@ class ReverseTranslator:
         """
         High-CAI profile: use only preferred codons
 
-        - CAI > 0.85 guaranteed
+        - Selects codons that maximize the profile golden-set CAI reference
         - No GC constraints
         """
         dna_seq: list[str] = []
@@ -671,6 +671,7 @@ class ReverseTranslator:
         protein_seq: str,
         profile: OptimizationProfile = OptimizationProfile.BALANCED,
         n: int = 5,
+        seed: int | None = None,
         **kwargs: Any,
     ) -> list[dict[str, Any]]:
         """
@@ -697,6 +698,9 @@ class ReverseTranslator:
         if n < 1:
             raise ValueError("n must be >= 1")
 
+        # Seed before any candidate generation (covers both n=1 fast path and n>1).
+        random.seed(seed if seed is not None else secrets.randbits(32))
+
         def _build_candidate() -> dict[str, Any]:
             dna_seq = self.reverse_translate(protein_seq, profile, **kwargs)
             cai = self.calculate_cai(dna_seq)
@@ -720,7 +724,6 @@ class ReverseTranslator:
 
         candidates: list[dict[str, Any]] = []
         last_error: Exception | None = None
-        random.seed(secrets.randbits(32))
 
         for attempt in range(n):
             try:

{factorforge_cds-3.1.9 → factorforge_cds-3.2.1}/src/factorforge/engines/profile/validator.py

@@ -90,14 +90,23 @@ class InputValidator:
         # Analyze character set
         unique_chars = set(clean_seq)
 
-        # DNA: only ATGC or ATGC + IUPAC codes
-        if unique_chars <= (self.DNA_BASES | self.AMBIGUOUS_DNA):
+        # 1. Pure ATGC → unambiguously DNA
+        if unique_chars <= self.DNA_BASES:
             return SequenceType.DNA
 
-        # Protein: amino acid characters
+        # 2. Protein check BEFORE ambiguous DNA.
+        #    IUPAC ambiguous codes (N/R/Y/S/W/K/M/B/D/H/V) overlap with amino acid
+        #    single-letter codes. When a sequence contains only overlapping characters,
+        #    protein interpretation takes priority — the optimizer's primary input is
+        #    protein → CDS. Users passing ambiguous DNA for re-domestication should
+        #    use FASTA format with a header line.
         if unique_chars <= (self.STANDARD_AA | set(self.AMBIGUOUS_AA.keys())):
             return SequenceType.PROTEIN
 
+        # 3. DNA with IUPAC ambiguous bases (only reached if non-protein chars present)
+        if unique_chars <= (self.DNA_BASES | self.AMBIGUOUS_DNA):
+            return SequenceType.DNA
+
         return SequenceType.UNKNOWN
 
     def validate(self, sequence: str, auto_fix: bool = False) -> dict[str, Any]:

factorforge_cds-3.2.1/src/factorforge/io/__init__.py

@@ -0,0 +1,14 @@
+"""Privacy-aware native sequence I/O helpers."""
+
+from .fasta import FastaRecord, format_fasta, parse_fasta, read_fasta, write_fasta
+from .validation import SequenceValidationError, validate_sequence
+
+__all__ = [
+    "FastaRecord",
+    "SequenceValidationError",
+    "format_fasta",
+    "parse_fasta",
+    "read_fasta",
+    "validate_sequence",
+    "write_fasta",
+]

factorforge_cds-3.2.1/src/factorforge/io/fasta.py

@@ -0,0 +1,132 @@
+"""Small native FASTA reader/writer with privacy-safe output headers."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Mapping
+
+from .validation import validate_sequence
+
+HEADER_ALLOWLIST = ("engine", "host_profile", "profile", "sequence_hash")
+BLOCKED_HEADER_TERMS = (
+    "plantform",
+    "confidential",
+    "private",
+    "secret",
+    "partner",
+    "yield",
+    "wet-lab",
+    "wet_lab",
+    "clinical",
+)
+RAW_SEQUENCE_PATTERN = re.compile(r"[ACGTRYSWKMBDHVN]{20,}", re.IGNORECASE)
+SAFE_HEADER_VALUE = re.compile(r"^[A-Za-z0-9_.:@/+ -]+$")
+
+
+@dataclass(frozen=True)
+class FastaRecord:
+    identifier: str
+    sequence: str
+    metadata: Mapping[str, str] = field(default_factory=dict)
+
+
+def _validate_header_value(value: str) -> str:
+    normalized = str(value).strip()
+    lowered = normalized.lower()
+    if not normalized or len(normalized) > 120:
+        raise ValueError("FASTA header values must contain 1-120 characters")
+    if any(term in lowered for term in BLOCKED_HEADER_TERMS):
+        raise ValueError("FASTA header contains blocked private or claim-related metadata")
+    if RAW_SEQUENCE_PATTERN.search(normalized):
+        raise ValueError("FASTA header must not contain a raw sequence")
+    if not SAFE_HEADER_VALUE.fullmatch(normalized):
+        raise ValueError("FASTA header contains unsupported characters")
+    return normalized
+
+
+def build_fasta_header(identifier: str, metadata: Mapping[str, object] | None = None) -> str:
+    """Build an allowlist-only public FASTA header."""
+    parts = [_validate_header_value(identifier)]
+    for key in HEADER_ALLOWLIST:
+        if metadata is None or key not in metadata or metadata[key] is None:
+            continue
+        value = _validate_header_value(str(metadata[key]))
+        parts.append(f"{key}={value}")
+    return " ".join(parts)
+
+
+def parse_fasta(text: str, validation_mode: str | None = None) -> list[FastaRecord]:
+    """Parse FASTA text, optionally validating each sequence alphabet."""
+    records: list[FastaRecord] = []
+    identifier: str | None = None
+    sequence_lines: list[str] = []
+
+    def append_record() -> None:
+        if identifier is None:
+            return
+        sequence = "".join(sequence_lines)
+        if validation_mode is not None:
+            sequence = validate_sequence(sequence, validation_mode)
+        records.append(FastaRecord(identifier=identifier, sequence=sequence))
+
+    for line_no, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith(";"):
+            continue
+        if line.startswith(">"):
+            append_record()
+            identifier = line[1:].strip()
+            if not identifier:
+                raise ValueError(f"FASTA header at line {line_no} is empty")
+            sequence_lines = []
+        elif identifier is None:
+            raise ValueError(f"FASTA sequence found before first header at line {line_no}")
+        else:
+            sequence_lines.append(line)
+
+    append_record()
+    if not records:
+        raise ValueError("FASTA input contains no records")
+    return records
+
+
+def format_fasta(
+    records: Iterable[FastaRecord],
+    *,
+    validation_mode: str = "dna_strict",
+    line_width: int = 60,
+) -> str:
+    """Serialize records using privacy-safe headers and validated sequences."""
+    if line_width < 1:
+        raise ValueError("line_width must be positive")
+
+    lines: list[str] = []
+    for record in records:
+        header = build_fasta_header(record.identifier, record.metadata)
+        sequence = validate_sequence(record.sequence, validation_mode)
+        lines.append(f">{header}")
+        lines.extend(sequence[i : i + line_width] for i in range(0, len(sequence), line_width))
+    if not lines:
+        raise ValueError("At least one FASTA record is required")
+    return "\n".join(lines) + "\n"
+
+
+def read_fasta(path: str | Path, validation_mode: str | None = None) -> list[FastaRecord]:
+    return parse_fasta(Path(path).read_text(encoding="utf-8"), validation_mode)
+
+
+def write_fasta(
+    path: str | Path,
+    records: Iterable[FastaRecord],
+    *,
+    validation_mode: str = "dna_strict",
+    line_width: int = 60,
+) -> Path:
+    output_path = Path(path)
+    output_path.write_text(
+        format_fasta(records, validation_mode=validation_mode, line_width=line_width),
+        encoding="utf-8",
+    )
+    return output_path

factorforge_cds-3.2.1/src/factorforge/io/validation.py

@@ -0,0 +1,48 @@
+"""Explicit DNA/protein alphabet validation without raw-sequence leakage."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Final
+
+VALIDATION_ALPHABETS: Final[dict[str, frozenset[str]]] = {
+    "dna_strict": frozenset("ACGT"),
+    "dna_iupac": frozenset("ACGTRYSWKMBDHVN"),
+    "protein_strict": frozenset("ACDEFGHIKLMNPQRSTVWY"),
+    "protein_extended": frozenset("ACDEFGHIKLMNPQRSTVWYXBZUO*"),
+}
+
+
+class SequenceValidationError(ValueError):
+    """Raised when a sequence does not satisfy its explicit alphabet contract."""
+
+
+def _fingerprint(sequence: str) -> str:
+    return hashlib.sha256(sequence.encode("utf-8")).hexdigest()[:12]
+
+
+def validate_sequence(sequence: str, mode: str = "dna_strict") -> str:
+    """Normalize and validate a sequence for the requested alphabet mode.
+
+    Whitespace is removed and letters are uppercased. Error messages include a
+    short preview and fingerprint, never the complete input sequence.
+    """
+    if mode not in VALIDATION_ALPHABETS:
+        choices = ", ".join(sorted(VALIDATION_ALPHABETS))
+        raise ValueError(f"Unknown validation mode {mode!r}; expected one of: {choices}")
+    if not isinstance(sequence, str):
+        raise TypeError("sequence must be a string")
+
+    normalized = re.sub(r"\s+", "", sequence).upper()
+    if not normalized:
+        raise SequenceValidationError("Sequence is empty after whitespace normalization")
+
+    invalid = sorted(set(normalized) - VALIDATION_ALPHABETS[mode])
+    if invalid:
+        preview = normalized[:8] + ("[truncated]" if len(normalized) > 8 else "")
+        raise SequenceValidationError(
+            f"Invalid symbols for {mode}: {invalid}; preview={preview!r}; "
+            f"length={len(normalized)}; sha256-prefix={_fingerprint(normalized)}"
+        )
+    return normalized

factorforge_cds-3.2.1/src/factorforge/protein_risk/__init__.py

@@ -0,0 +1,5 @@
+"""Deterministic protein structural-risk annotations."""
+
+from factorforge.protein_risk.annotate import annotate_protein_risk
+
+__all__ = ["annotate_protein_risk"]

factorforge_cds-3.2.1/src/factorforge/protein_risk/annotate.py

@@ -0,0 +1,32 @@
+"""Compose protein structural-risk annotations."""
+
+from factorforge.protein_risk.risk_classifier import classify_risk
+from factorforge.protein_risk.sp_predict import predict_signal_peptide
+from factorforge.protein_risk.tm_predict import predict_tm_segments
+
+
+def annotate_protein_risk(protein_seq: str) -> dict:
+    """Return deterministic structural-risk indicators without sequence material."""
+    tm_prediction = predict_tm_segments(protein_seq)
+    sp_predicted = predict_signal_peptide(protein_seq)
+    risk_level = classify_risk(
+        tm_prediction["tm_count"],
+        tm_prediction["mean_kd_score"],
+        sp_predicted,
+    )
+
+    warnings = []
+    if risk_level != "LOW":
+        warnings.append(
+            "Protein structural risk indicator: "
+            f"{risk_level} (tm_count={tm_prediction['tm_count']}). "
+            "CDS-level checks are independent of protein structural risk."
+        )
+
+    return {
+        "tm_count": tm_prediction["tm_count"],
+        "mean_kd_score": tm_prediction["mean_kd_score"],
+        "signal_peptide_predicted": sp_predicted,
+        "risk_level": risk_level,
+        "warnings": warnings,
+    }