factorforge-cds 3.0.0__py3-none-any.whl

factorforge/engines/v2/validator.py

@@ -0,0 +1,383 @@
+"""
+Input Validator for FactorForge v2
+Input validation and preprocessing module (P0-1)
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Any
+
+
+class SequenceType(Enum):
+    """Sequence type enum"""
+
+    PROTEIN = "protein"
+    DNA = "dna"
+    FASTA = "fasta"
+    UNKNOWN = "unknown"
+
+
+class ValidationLevel(Enum):
+    """Validation level"""
+
+    VALID = "valid"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class InputValidator:
+    """
+    Input sequence validation and preprocessing
+
+    Features:
+    - Auto-detect AA/DNA/FASTA
+    - Real-time input validation
+    - Handle frame errors, stop codons, non-standard AAs
+    """
+
+    # Standard amino acids (20 + STOP)
+    STANDARD_AA = set("ACDEFGHIKLMNPQRSTVWY*")
+
+    # Ambiguous amino acids
+    AMBIGUOUS_AA = {
+        "B": "Asx (Asn or Asp)",
+        "Z": "Glx (Gln or Glu)",
+        "X": "Xaa (Unknown)",
+        "J": "Xle (Leu or Ile)",
+        "U": "Sec (Selenocysteine)",
+        "O": "Pyl (Pyrrolysine)",
+    }
+
+    # DNA bases
+    DNA_BASES = set("ATGC")
+    AMBIGUOUS_DNA = set("NRYSWKMBDHV")  # IUPAC ambiguity codes
+
+    def __init__(self) -> None:
+        """Initialize"""
+        self.warnings: list[dict[str, Any]] = []
+        self.errors: list[dict[str, Any]] = []
+
+    def detect_sequence_type(self, sequence: str) -> SequenceType:
+        """
+        Auto-detect sequence type
+
+        Args:
+            sequence: Input sequence (may include whitespace)
+
+        Returns:
+            SequenceType enum
+
+        Raises:
+            None.
+
+        Examples:
+            >>> validator = InputValidator()
+            >>> validator.detect_sequence_type("ATGC").value
+            'dna'
+        """
+        # Remove whitespace and newlines
+        clean_seq = re.sub(r"\s+", "", sequence).upper()
+
+        if not clean_seq:
+            return SequenceType.UNKNOWN
+
+        # Check FASTA format (starts with '>')
+        if sequence.strip().startswith(">"):
+            return SequenceType.FASTA
+
+        # Analyze character set
+        unique_chars = set(clean_seq)
+
+        # DNA: only ATGC or ATGC + IUPAC codes
+        if unique_chars <= (self.DNA_BASES | self.AMBIGUOUS_DNA):
+            return SequenceType.DNA
+
+        # Protein: amino acid characters
+        if unique_chars <= (self.STANDARD_AA | set(self.AMBIGUOUS_AA.keys())):
+            return SequenceType.PROTEIN
+
+        return SequenceType.UNKNOWN
+
+    def validate(self, sequence: str, auto_fix: bool = False) -> dict[str, Any]:
+        """
+        Validate input sequence
+
+        Args:
+            sequence: Input sequence
+            auto_fix: Whether to auto-fix
+
+        Returns:
+            {
+                "type": "protein|dna|fasta|unknown",
+                "valid": True/False,
+                "level": "valid|warning|error",
+                "warnings": [...],
+                "errors": [...],
+                "metadata": {...},
+                "processed_sequence": "..."  # Preprocessed sequence
+            }
+
+        Raises:
+            None.
+
+        Examples:
+            >>> validator = InputValidator()
+            >>> result = validator.validate("ATG GCC TAA")
+            >>> result["type"]
+            'dna'
+        """
+        self.warnings = []
+        self.errors = []
+
+        # 1. Detect sequence type
+        seq_type = self.detect_sequence_type(sequence)
+
+        # 2. Type-specific validation
+        if seq_type == SequenceType.FASTA:
+            return self._validate_fasta(sequence, auto_fix)
+        elif seq_type == SequenceType.DNA:
+            return self._validate_dna(sequence, auto_fix)
+        elif seq_type == SequenceType.PROTEIN:
+            return self._validate_protein(sequence, auto_fix)
+        else:
+            self.errors.append(
+                {
+                    "code": "UNKNOWN_TYPE",
+                    "message": "Unable to detect sequence type.",
+                    "suggestion": "Enter a DNA (ATGC) or Protein (20 AA) sequence.",
+                }
+            )
+            return self._build_result(seq_type, sequence)
+
+    def _validate_fasta(self, sequence: str, auto_fix: bool) -> dict[str, Any]:
+        """Validate FASTA format"""
+        lines = sequence.strip().split("\n")
+
+        if not lines[0].startswith(">"):
+            self.errors.append(
+                {"code": "INVALID_FASTA", "message": "Missing FASTA header (must start with '>')."}
+            )
+            return self._build_result(SequenceType.FASTA, sequence)
+
+        # Extract header
+        header = lines[0][1:].strip()
+
+        # Extract sequence lines
+        seq_lines = [
+            line.strip() for line in lines[1:] if line.strip() and not line.startswith(">")
+        ]
+        seq_content = "".join(seq_lines)
+
+        # Recursively validate sequence content
+        seq_result = self.validate(seq_content, auto_fix)
+
+        # Add FASTA metadata
+        seq_result["fasta_header"] = header
+        seq_result["type"] = SequenceType.FASTA.value
+
+        return seq_result
+
+    def _validate_dna(self, sequence: str, auto_fix: bool) -> dict[str, Any]:
+        """Validate DNA sequence"""
+        clean_seq = re.sub(r"\s+", "", sequence).upper()
+
+        # 1. Check invalid bases
+        invalid_chars = set(clean_seq) - (self.DNA_BASES | self.AMBIGUOUS_DNA)
+        if invalid_chars:
+            self.errors.append(
+                {
+                    "code": "INVALID_DNA_CHARS",
+                    "message": f"Invalid DNA bases: {', '.join(invalid_chars)}",
+                    "suggestion": "Use only ATGC or IUPAC codes.",
+                }
+            )
+
+        # 2. Warn on ambiguous bases
+        ambiguous_chars = set(clean_seq) & self.AMBIGUOUS_DNA
+        if ambiguous_chars:
+            self.warnings.append(
+                {
+                    "code": "AMBIGUOUS_DNA",
+                    "message": f"Ambiguous bases found: {', '.join(ambiguous_chars)}",
+                    "suggestion": "Consider replacing with exact bases.",
+                }
+            )
+
+        # 3. Frame check (multiple of 3)
+        if len(clean_seq) % 3 != 0:
+            remainder = len(clean_seq) % 3
+            self.warnings.append(
+                {
+                    "code": "FRAME_ERROR",
+                    "message": f"Sequence length is not a multiple of 3 ({len(clean_seq)} bp).",
+                    "suggestion": f"Remove or add the last {remainder} bp.",
+                    "auto_fix_option": {
+                        "trim_end": len(clean_seq) - remainder,
+                        "trim_start": len(clean_seq) - 3 + remainder,
+                    },
+                }
+            )
+
+            if auto_fix:
+                clean_seq = clean_seq[: len(clean_seq) - remainder]
+                self.warnings[-1]["auto_fixed"] = True
+
+        # 4. Stop codon check
+        stop_codons = {"TAA", "TAG", "TGA"}
+        stop_positions = []
+
+        for i in range(0, len(clean_seq) - 2, 3):
+            codon = clean_seq[i : i + 3]
+            if codon in stop_codons:
+                codon_pos = i // 3 + 1  # 1-indexed
+                stop_positions.append(codon_pos)
+
+        # Warn on internal stop codons
+        if len(stop_positions) > 1 or (
+            len(stop_positions) == 1 and stop_positions[0] != len(clean_seq) // 3
+        ):
+            self.warnings.append(
+                {
+                    "code": "INTERNAL_STOP",
+                    "message": f"Internal stop codon found: positions {stop_positions}",
+                    "suggestion": "Verify whether this is intended.",
+                }
+            )
+
+        # 5. GC content
+        gc_count = clean_seq.count("G") + clean_seq.count("C")
+        gc_content = (gc_count / len(clean_seq) * 100) if clean_seq else 0
+
+        # Warn on extreme GC content
+        if gc_content < 30 or gc_content > 70:
+            self.warnings.append(
+                {
+                    "code": "EXTREME_GC",
+                    "message": f"GC content is extreme: {gc_content:.1f}%",
+                    "suggestion": "Recommended range is 30-70%.",
+                }
+            )
+
+        metadata = {
+            "length": len(clean_seq),
+            "gc_content": round(gc_content, 2),
+            "has_stop": len(stop_positions) > 0,
+            "stop_positions": stop_positions,
+            "ambiguous_bases": list(ambiguous_chars),
+        }
+
+        return self._build_result(SequenceType.DNA, clean_seq, metadata)
+
+    def _validate_protein(self, sequence: str, auto_fix: bool) -> dict[str, Any]:
+        """Validate protein sequence"""
+        clean_seq = re.sub(r"\s+", "", sequence).upper()
+
+        # 1. Check invalid amino acids
+        invalid_chars = set(clean_seq) - (self.STANDARD_AA | set(self.AMBIGUOUS_AA.keys()))
+        if invalid_chars:
+            self.errors.append(
+                {
+                    "code": "INVALID_AA_CHARS",
+                    "message": f"Invalid amino acids: {', '.join(invalid_chars)}",
+                    "suggestion": "Use only standard 20 AAs or * (STOP).",
+                }
+            )
+
+        # 2. Warn on ambiguous AAs
+        ambiguous_found = {}
+        for aa in self.AMBIGUOUS_AA:
+            if aa in clean_seq:
+                ambiguous_found[aa] = self.AMBIGUOUS_AA[aa]
+
+        if ambiguous_found:
+            self.warnings.append(
+                {
+                    "code": "AMBIGUOUS_AA",
+                    "message": f"Ambiguous amino acids found: {ambiguous_found}",
+                    "suggestion": "Consider replacing with specific amino acids.",
+                }
+            )
+
+        # 3. Internal STOP check
+        stop_positions = [i + 1 for i, aa in enumerate(clean_seq) if aa == "*"]
+
+        if len(stop_positions) > 1 or (
+            len(stop_positions) == 1 and stop_positions[0] != len(clean_seq)
+        ):
+            self.warnings.append(
+                {
+                    "code": "INTERNAL_STOP",
+                    "message": f"Internal stop codon found: positions {stop_positions}",
+                    "suggestion": "Verify whether this is intended.",
+                }
+            )
+
+        metadata = {
+            "length": len(clean_seq),
+            "has_stop": len(stop_positions) > 0,
+            "stop_positions": stop_positions,
+            "ambiguous_aa": ambiguous_found,
+        }
+
+        return self._build_result(SequenceType.PROTEIN, clean_seq, metadata)
+
+    def _build_result(
+        self,
+        seq_type: SequenceType,
+        processed_seq: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Build validation result"""
+        # Determine validation level
+        if self.errors:
+            level = ValidationLevel.ERROR
+            valid = False
+        elif self.warnings:
+            level = ValidationLevel.WARNING
+            valid = True
+        else:
+            level = ValidationLevel.VALID
+            valid = True
+
+        return {
+            "type": seq_type.value,
+            "valid": valid,
+            "level": level.value,
+            "warnings": self.warnings,
+            "errors": self.errors,
+            "metadata": metadata or {},
+            "processed_sequence": processed_seq,
+        }
+
+
+# --- Usage example ---
+if __name__ == "__main__":
+    import json
+
+    validator = InputValidator()
+
+    # Test case 1: DNA sequence (valid)
+    print("=== Test 1: Valid DNA ===")
+    result1 = validator.validate("ATG GCC AAA TAA")
+    print(json.dumps(result1, indent=2, ensure_ascii=False))
+
+    # Test case 2: DNA sequence (frame error)
+    print("\n=== Test 2: DNA with frame error ===")
+    result2 = validator.validate("ATGGCCAA", auto_fix=True)
+    print(json.dumps(result2, indent=2, ensure_ascii=False))
+
+    # Test case 3: Protein sequence (ambiguous AA)
+    print("\n=== Test 3: Protein with ambiguous AA ===")
+    result3 = validator.validate("MAKXLF*")
+    print(json.dumps(result3, indent=2, ensure_ascii=False))
+
+    # Test case 4: FASTA format
+    print("\n=== Test 4: FASTA format ===")
+    fasta_input = """>GFP_test
+ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGG
+GTGGTGCCCATCCTGGTCGAGCTGGACGGCGAC
+TAA"""
+    result4 = validator.validate(fasta_input)
+    print(json.dumps(result4, indent=2, ensure_ascii=False))

factorforge/engines/v3/__init__.py

@@ -0,0 +1,12 @@
+"""
+FactorForge v3 - BART decoder scaffolding.
+"""
+
+from __future__ import annotations
+
+__version__ = "3.0.0"
+
+from .pipeline import V3Optimizer, V3Pipeline
+from .tokenizer import AATokenizer, CodonTokenizer
+
+__all__ = ["AATokenizer", "CodonTokenizer", "V3Optimizer", "V3Pipeline"]

factorforge/engines/v3/explain.py

@@ -0,0 +1,119 @@
+"""FDA-style explainability report helpers for FactorForge v3."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_RESTRICTION_SITES: dict[str, str] = {
+    "EcoRI": "GAATTC",
+    "BamHI": "GGATCC",
+    "BsaI": "GGTCTC",
+    "BsmBI": "CGTCTC",
+    "NotI": "GCGGCCGC",
+}
+
+
+@dataclass(frozen=True)
+class ExplainabilityInputs:
+    aa_sequence: str
+    dna_sequence: str
+    metrics: dict[str, float]
+    model_id: str
+    tokenizer_hash: str
+    seed: int
+    config: dict[str, Any]
+    post_guard: dict[str, Any] | None = None
+
+
+def build_fda_report(inputs: ExplainabilityInputs) -> dict[str, Any]:
+    aa_seq = inputs.aa_sequence
+    dna_seq = inputs.dna_sequence
+
+    return {
+        "model": {
+            "id": inputs.model_id,
+            "hash": _hash_string(inputs.model_id),
+        },
+        "tokenizer": {
+            "hash": inputs.tokenizer_hash,
+        },
+        "inputs": {
+            "aa_length": len(aa_seq),
+        },
+        "outputs": {
+            "dna_length": len(dna_seq),
+            "cai": float(inputs.metrics.get("cai", 0.0)),
+            "gc_percent": float(inputs.metrics.get("gc_content", 0.0)),
+        },
+        "constraint_checks": _constraint_checks(dna_seq),
+        "post_guard": inputs.post_guard or {},
+        "determinism": {
+            "seed": inputs.seed,
+            "config": inputs.config,
+        },
+    }
+
+
+def write_fda_report(path: str, report: dict[str, Any]) -> None:
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(report, handle, indent=2, sort_keys=True)
+
+
+def _constraint_checks(sequence: str) -> dict[str, Any]:
+    return {
+        "poly_a_runs": _scan_poly_a(sequence),
+        "restriction_sites": _scan_restriction_sites(sequence, DEFAULT_RESTRICTION_SITES),
+        "splice_like_motifs": _scan_splice_like(sequence),
+        "homopolymers": _scan_homopolymers(sequence),
+        "repeats": _scan_repeats(sequence),
+    }
+
+
+def _scan_poly_a(sequence: str, min_len: int = 6) -> list[dict[str, int]]:
+    matches = re.finditer(rf"A{{{min_len},}}", sequence)
+    return [{"start": m.start(), "end": m.end()} for m in matches]
+
+
+def _scan_restriction_sites(
+    sequence: str, sites: dict[str, str]
+) -> list[dict[str, Any]]:
+    hits: list[dict[str, Any]] = []
+    for enzyme, motif in sites.items():
+        positions = [m.start() for m in re.finditer(motif, sequence)]
+        if positions:
+            hits.append({"enzyme": enzyme, "motif": motif, "positions": positions})
+    return hits
+
+
+def _scan_splice_like(sequence: str) -> list[dict[str, int]]:
+    matches = re.finditer(r"GT[ACGT]{2,20}AG", sequence)
+    return [{"start": m.start(), "end": m.end()} for m in matches]
+
+
+def _scan_homopolymers(sequence: str, min_len: int = 6) -> list[dict[str, Any]]:
+    runs: list[dict[str, Any]] = []
+    for base in "ACGT":
+        for match in re.finditer(rf"{base}{{{min_len},}}", sequence):
+            runs.append({"base": base, "start": match.start(), "end": match.end()})
+    return runs
+
+
+def _scan_repeats(sequence: str, kmer: int = 6) -> list[dict[str, Any]]:
+    seen: dict[str, list[int]] = {}
+    for idx in range(0, max(0, len(sequence) - kmer + 1)):
+        token = sequence[idx : idx + kmer]
+        seen.setdefault(token, []).append(idx)
+
+    repeats: list[dict[str, Any]] = []
+    for token, positions in seen.items():
+        if len(positions) > 1:
+            repeats.append({"kmer": token, "positions": positions})
+    return repeats
+
+
+def _hash_string(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()

factorforge/engines/v3/inference/__init__.py

@@ -0,0 +1,6 @@
+"""Inference adapters for FactorForge v3-alpha."""
+
+from .v2_adapter import optimize_with_v2
+
+__all__ = ["optimize_with_v2"]
+

factorforge/engines/v3/inference/constrained_decoder.py

@@ -0,0 +1,80 @@
+"""Constrained v3 decoding and fallback helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import torch
+
+from factorforge.engines.v3.inference.v2_adapter import optimize_with_v2
+from factorforge.engines.v3.synonym_mask import build_synonym_token_mask, normalize_protein_sequence
+from factorforge.engines.v3.tokenizer import CodonTokenizer
+from factorforge.utils.validation import validate_candidate_sequence
+
+
+def constrained_greedy_decode(
+    decoder: Any,
+    encoder_hidden_states: torch.Tensor,
+    protein_sequence: str,
+    codon_tokenizer: CodonTokenizer,
+) -> torch.Tensor:
+    """Greedy decode one codon per amino acid under a synonym mask."""
+    protein = normalize_protein_sequence(protein_sequence)
+    mask = build_synonym_token_mask(
+        protein,
+        codon_tokenizer.token_to_id,
+        device=encoder_hidden_states.device,
+    )
+    batch_size = int(encoder_hidden_states.shape[0])
+    if batch_size != 1:
+        raise ValueError("constrained_greedy_decode currently supports batch_size=1")
+
+    decoder_input_ids = torch.full(
+        (1, 1),
+        codon_tokenizer.bos_token_id,
+        dtype=torch.long,
+        device=encoder_hidden_states.device,
+    )
+    generated: list[torch.Tensor] = []
+    for position in range(len(protein)):
+        logits = decoder(
+            encoder_hidden_states=encoder_hidden_states,
+            decoder_input_ids=decoder_input_ids,
+        )
+        next_logits = logits[:, -1, :].masked_fill(~mask[position].unsqueeze(0), -1.0e9)
+        next_token = torch.argmax(next_logits, dim=-1)
+        generated.append(next_token)
+        decoder_input_ids = torch.cat([decoder_input_ids, next_token.unsqueeze(1)], dim=1)
+
+    eos = torch.tensor(
+        [[codon_tokenizer.eos_token_id]],
+        dtype=torch.long,
+        device=encoder_hidden_states.device,
+    )
+    return torch.cat([decoder_input_ids, eos], dim=1)
+
+
+def validate_candidate_or_fallback(
+    protein_sequence: str,
+    dna_sequence: str,
+    fallback_options: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return a valid v3 candidate or deterministic v2 fallback metadata."""
+    protein = normalize_protein_sequence(protein_sequence)
+    validator = validate_candidate_sequence(protein, dna_sequence)
+    if validator["passed"]:
+        return {
+            "engine": "v3",
+            "protein_sequence": protein,
+            "dna_sequence": dna_sequence,
+            "validator": validator,
+            "fallback_used": False,
+            "warnings": list(validator["warnings"]),
+            "errors": [],
+        }
+
+    fallback = optimize_with_v2(protein, options=fallback_options)
+    fallback["fallback_used"] = True
+    fallback.setdefault("metadata", {})["fallback_reason"] = validator["errors"]
+    return fallback
+

factorforge/engines/v3/inference/v2_adapter.py

@@ -0,0 +1,72 @@
+"""Formal v2 adapter for v3-alpha baseline, teacher, and fallback use."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from factorforge.engines.v2.rules.reverse_translator import OptimizationProfile, ReverseTranslator
+from factorforge.engines.v2.rules.rule_engine import RuleEngine
+from factorforge.engines.v2.scoring import calculate_composite_score
+from factorforge.engines.v3.metrics import load_codon_usage_table
+from factorforge.ml.metrics import calculate_cai, calculate_gc
+from factorforge.utils.validation import validate_candidate_sequence
+
+
+def optimize_with_v2(
+    protein_sequence: str,
+    options: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Optimize a protein sequence with v2 semantics and return v3-alpha metadata."""
+    opts = options or {}
+    profile_name = str(opts.get("profile", "high_cai")).lower()
+    scan_mode = str(opts.get("scan_mode", "fast"))
+    try:
+        profile = OptimizationProfile(profile_name)
+    except ValueError as exc:
+        supported = ", ".join(item.value for item in OptimizationProfile)
+        raise ValueError(f"Unknown v2 profile: {profile_name}. Supported profiles: {supported}") from exc
+
+    protein = "".join(protein_sequence.upper().split()).rstrip("*")
+    if not protein:
+        raise ValueError("protein_sequence must not be empty")
+
+    translator = ReverseTranslator()
+    candidates = translator.generate_candidates(protein, profile=profile, n=1)
+    dna_sequence = candidates[0]["sequence"]
+    table = load_codon_usage_table()
+    metrics = {
+        "cai": calculate_cai(dna_sequence, table.codon_weights),
+        "gc": calculate_gc(dna_sequence),
+        "gc_content": calculate_gc(dna_sequence),
+        "score": calculate_composite_score(
+            cai=candidates[0]["cai"],
+            gc=candidates[0]["gc"],
+            sequence=dna_sequence,
+            profile=profile.value,
+        ),
+    }
+
+    rule_engine = RuleEngine()
+    scan_results = rule_engine.scan_all(dna_sequence, mode=scan_mode)
+    validator = validate_candidate_sequence(protein, dna_sequence)
+    warnings = list(validator["warnings"])
+    errors = list(validator["errors"])
+    violation_count = sum(len(value) for value in scan_results.values())
+    if violation_count:
+        warnings.append(f"v2 rule scan reported {violation_count} violation(s)")
+
+    return {
+        "engine": "v2",
+        "protein_sequence": protein,
+        "dna_sequence": dna_sequence,
+        "metrics": metrics,
+        "validator": validator,
+        "warnings": warnings,
+        "errors": errors,
+        "metadata": {
+            "profile": profile.value,
+            "scan_mode": scan_mode,
+            "scan_results": scan_results,
+        },
+    }
+