factorforge-cds 3.0.0__py3-none-any.whl

factorforge/__init__.py

@@ -0,0 +1,19 @@
+"""
+FactorForge - Codon Optimization Platform
+
+v1_archived: Rule-based v1 (Archived)
+v2: Rule-based (Production) — engine version 3.0.0
+v3: ML engine / v3-alpha (ESM2 + BART, in development)
+"""
+
+__version__ = "3.0.0"
+__author__ = "Eijex"
+
+# Auto-register engines (safe when running from source tree)
+try:
+    from .engines import EngineRegistry, register_builtin_engines
+
+    register_builtin_engines()
+    __all__ = ["EngineRegistry"]
+except Exception:
+    __all__ = ["__version__"]

factorforge/__main__.py

@@ -0,0 +1,8 @@
+"""CLI Entry Point"""
+
+import sys
+
+from factorforge.cli.main import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())

factorforge/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI module"""
+
+from .main import cli
+
+__all__ = ["cli"]

factorforge/cli/legacy_cli.py

@@ -0,0 +1,157 @@
+"""
+FactorForge Command Line Interface
+For Linux servers and automation
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Add src root to path
+src_root = next(p for p in Path(__file__).resolve().parents if p.name == "src")
+sys.path.insert(0, str(src_root))
+
+def main():
+    parser = argparse.ArgumentParser(description="FactorForge - AI-Powered Codon Optimization")
+
+    parser.add_argument("input", help="Input DNA sequence or FASTA file")
+
+    parser.add_argument("-o", "--output", help="Output file (JSON format)", default=None)
+
+    parser.add_argument(
+        "-m", "--model", help="Model checkpoint path", default="outputs/checkpoints/phase3"
+    )
+
+    parser.add_argument("--batch", action="store_true", help="Process as FASTA file (batch mode)")
+
+    parser.add_argument("--verbose", action="store_true", help="Verbose output")
+
+    args = parser.parse_args()
+
+    try:
+        from factorforge.engines.v1_archived.evaluation.metrics import BiologicalMetrics
+        from factorforge.engines.v1_archived.tokenization.codon_tokenizer import CodonTokenizer
+    except ImportError as exc:
+        raise SystemExit(
+            "v1 dependencies not installed. Install with: pip install -e \".[v1]\""
+        ) from exc
+
+    # Load tokenizer
+    if args.verbose:
+        print(f"Loading tokenizer from {args.model}...")
+
+    tokenizer_path = Path(args.model) / "tokenizer"
+    if not tokenizer_path.exists():
+        print(f"Error: Tokenizer not found at {tokenizer_path}")
+        return
+
+    tokenizer = CodonTokenizer.load(str(tokenizer_path))
+
+    # Get sequence
+    sequences = []
+    if Path(args.input).exists():
+        # File input
+        with open(args.input) as f:
+            content = f.read()
+
+        # Handle FASTA
+        if content.startswith(">"):
+            if args.batch:
+                sequences = parse_fasta(content)
+            else:
+                sequences = [extract_first_sequence(content)]
+        else:
+            sequences = [content.strip()]
+    else:
+        # Direct sequence input
+        sequences = [args.input]
+
+    # Process sequences
+    results = []
+    bio = BiologicalMetrics()
+
+    for i, seq in enumerate(sequences):
+        # Clean sequence
+        seq = "".join(c for c in seq.upper() if c in "ATGC")
+
+        if len(seq) == 0:
+            continue
+
+        if len(seq) % 3 != 0:
+            if args.verbose:
+                print(f"Warning: Sequence {i+1} length not multiple of 3, skipping...")
+            continue
+
+        # Tokenize
+        tokens = tokenizer.encode(seq)
+
+        # Metrics
+        metrics = bio.evaluate_sequence_quality(seq)
+        is_quality, checks = bio.is_high_quality(seq)
+
+        result = {
+            "sequence_id": i + 1,
+            "length": len(seq),
+            "num_tokens": len(tokens),
+            "compression_ratio": round(len(seq) / len(tokens), 2) if len(tokens) > 0 else 0,
+            "gc_content": metrics["gc_content"],
+            "cai": metrics["cai"],
+            "rare_codon_freq": metrics["rare_codon_freq"],
+            "high_quality": is_quality,
+            "quality_checks": checks,
+        }
+
+        results.append(result)
+
+        if args.verbose:
+            print(f"\nSequence {i+1}:")
+            print(f"  Length: {result['length']} bp")
+            print(f"  Tokens: {result['num_tokens']}")
+            print(f"  GC%: {result['gc_content']:.1f}%")
+            print(f"  CAI: {result['cai']:.3f}")
+            print(f"  Quality: {'✅ PASS' if is_quality else '❌ FAIL'}")
+
+    # Output
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump(results, f, indent=2)
+        print(f"\n✅ Results saved to {args.output}")
+    else:
+        print("\n" + json.dumps(results, indent=2))
+
+
+def parse_fasta(content):
+    """Parse FASTA file with multiple sequences"""
+    sequences = []
+    current_seq = []
+
+    for line in content.split("\n"):
+        if line.startswith(">"):
+            if current_seq:
+                sequences.append("".join(current_seq))
+                current_seq = []
+        else:
+            current_seq.append(line.strip())
+
+    if current_seq:
+        sequences.append("".join(current_seq))
+
+    return sequences
+
+
+def extract_first_sequence(content):
+    """Extract first sequence from FASTA"""
+    lines = content.split("\n")
+    sequence = []
+
+    for line in lines:
+        if line.startswith(">"):
+            continue
+        sequence.append(line.strip())
+
+    return "".join(sequence)
+
+
+if __name__ == "__main__":
+    main()

factorforge/cli/main.py

@@ -0,0 +1,305 @@
+"""
+FactorForge CLI
+
+Usage:
+  factorforge optimize input.fasta -e v2 -p balanced -o output.fasta
+  factorforge optimize input.fasta -e v2 -p balanced --template standard_expression -o output.gb --format genbank
+  factorforge list-engines
+"""
+
+from pathlib import Path
+import sys
+
+import click
+
+from factorforge import __version__
+from factorforge.engines.registry import EngineRegistry
+from factorforge.engines.v2.utils import parse_fasta_records
+
+
+def _configure_stdio() -> None:
+    """Best-effort UTF-8 for Windows consoles."""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            reconfigure = getattr(stream, "reconfigure", None)
+            if callable(reconfigure):
+                reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+
+def _parse_csv_option(value):
+    """Parse comma-separated option values."""
+    if not value:
+        return None
+    parsed = [item.strip() for item in value.split(",") if item.strip()]
+    return parsed or None
+
+
+def _wrap_sequence(sequence, width=80):
+    """Wrap sequence to fixed-width lines."""
+    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):
+    """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.")
+    if gc_min > gc_max:
+        raise ValueError("--gc-min must be <= --gc-max.")
+
+    from factorforge.engines.v3.metrics import load_codon_usage_table
+    from factorforge.ml.feasibility import analyze_feasibility
+
+    table = load_codon_usage_table()
+    result = analyze_feasibility(
+        sequence,
+        table.codon_weights,
+        target_gc_low=gc_min,
+        target_gc_high=gc_max,
+    )
+    best = result["target"]["best_candidate"]
+    feasible = best is not None
+    if best is None:
+        best = result["best_candidate_without_gc"]
+    if best is None:
+        raise ValueError("No DP candidate generated.")
+
+    reason = (
+        f"Maximum CAI under GC {gc_min:g}-{gc_max:g}%"
+        if feasible
+        else "Maximum CAI without GC constraint; requested GC range was infeasible"
+    )
+    return best, result, reason
+
+
+def _format_dp_fasta(sequence_id: str, dna_sequence: str, cai: float, gc: float) -> str:
+    """Format a DP result as FASTA."""
+    header = f">{sequence_id}|engine=dp|objective=feasibility_best|cai={cai:.3f}|gc={gc:.2f}"
+    return f"{header}\n{_wrap_sequence(dna_sequence)}\n"
+
+
+@click.group()
+@click.version_option(version=__version__)
+def cli():
+    """FactorForge - Codon Optimization Platform"""
+    _configure_stdio()
+
+
+@cli.command()
+def list_engines():
+    """List available optimization engines"""
+    engines = EngineRegistry.list_engines()
+
+    click.echo("\nAvailable Engines:\n")
+    for name, info in engines.items():
+        click.echo(f"  - {name}: {info['name']} v{info['version']}")
+    click.echo()
+
+
+@cli.command()
+@click.argument("input_file", type=click.Path(exists=True))
+@click.option(
+    "--engine",
+    "-e",
+    default="dp",
+    type=click.Choice(["dp", "v2"], case_sensitive=False),
+    help="Engine (dp, v2)",
+)
+@click.option("--profile", "-p", default="balanced", help="Optimization profile")
+@click.option(
+    "--objective",
+    default="feasibility_best",
+    type=click.Choice(["feasibility_best", "gc_target", "high_cai"], case_sensitive=False),
+    help="DP objective",
+)
+@click.option("--gc-min", type=float, default=40.0, help="Minimum target GC percentage")
+@click.option("--gc-max", type=float, default=55.0, help="Maximum target GC percentage")
+@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(
+    "--scan-mode",
+    default="full",
+    type=click.Choice(["full", "fast"], case_sensitive=False),
+    help="Rule scan mode",
+)
+@click.option("--scan-include", help="Comma-separated scanner names to include")
+@click.option("--scan-exclude", help="Comma-separated scanner names to exclude")
+def optimize(
+    input_file,
+    engine,
+    profile,
+    objective,
+    gc_min,
+    gc_max,
+    construct_template,
+    output,
+    output_format,
+    scan_mode,
+    scan_include,
+    scan_exclude,
+):
+    """Optimize protein sequence"""
+    try:
+        # Read file
+        with open(input_file, encoding="utf-8") as f:
+            raw_input = f.read()
+
+        scan_include_list = _parse_csv_option(scan_include)
+        scan_exclude_list = _parse_csv_option(scan_exclude)
+
+        fasta_records = None
+        sequence = raw_input.strip()
+        if raw_input.lstrip().startswith(">"):
+            fasta_records = parse_fasta_records(raw_input)
+            if len(fasta_records) == 1:
+                sequence = fasta_records[0][1]
+
+        if fasta_records is not None and len(fasta_records) > 1:
+            if engine == "dp":
+                raise ValueError("Multi-FASTA input requires --engine v2.")
+            if construct_template:
+                raise ValueError("Multi-FASTA input does not support --template mode.")
+            if output_format.lower() != "fasta":
+                raise ValueError("Multi-FASTA input only supports FASTA output.")
+
+            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(
+                    payload,
+                    profile=profile,
+                    scan_mode=scan_mode,
+                    scan_include=scan_include_list,
+                    scan_exclude=scan_exclude_list,
+                )
+            else:
+                results = [
+                    optimizer.optimize(
+                        seq,
+                        profile=profile,
+                        scan_mode=scan_mode,
+                        scan_include=scan_include_list,
+                        scan_exclude=scan_exclude_list,
+                    )
+                    for _id, seq in fasta_records
+                ]
+
+            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(f"{header}\n{_wrap_sequence(result.sequence)}")
+            out_content = "\n".join(combined_fasta) + "\n"
+
+            if output:
+                with open(output, "w", encoding="utf-8") as f:
+                    f.write(out_content)
+                click.echo(f"Saved batch FASTA to: {output}")
+            else:
+                click.echo(f"\n{out_content}")
+            click.echo(f"Batch optimized: {len(results)} sequences")
+            return
+
+        if engine == "dp":
+            if construct_template:
+                raise ValueError("DP engine does not support --template mode.")
+            if output_format.lower() != "fasta":
+                raise ValueError("DP engine only supports FASTA output.")
+
+            best, feasibility, recommendation_reason = _build_dp_result(
+                sequence,
+                objective=objective,
+                gc_min=gc_min,
+                gc_max=gc_max,
+            )
+            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)
+
+            click.echo("Optimizing with DP feasibility engine...")
+            if output:
+                with open(output, "w", encoding="utf-8") as f:
+                    f.write(fasta)
+                click.echo(f"Saved to: {output}")
+            else:
+                click.echo(f"\n{fasta}")
+
+            click.echo("Metrics:")
+            click.echo(f"  - cai: {cai:.3f}")
+            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}")
+            click.echo(f"  - target_feasible: {bool(feasibility['target']['best_candidate'])}")
+            click.echo(f"  - recommendation_reason: {recommendation_reason}")
+            return
+
+        if engine == "v2" and construct_template:
+            from factorforge.engines.v2.pipeline import OptimizationPipeline
+
+            pipeline = OptimizationPipeline(profile=profile, construct_template=construct_template)
+            result = pipeline.run(
+                sequence,
+                scan_mode=scan_mode,
+                scan_include=scan_include_list,
+                scan_exclude=scan_exclude_list,
+            )
+
+            if output_format.lower() == "genbank" and not output:
+                raise ValueError("GenBank output requires --output file path.")
+
+            if output:
+                result.save(Path(output), format=output_format)
+                click.echo(f"Saved to: {output}")
+            else:
+                click.echo(f"\n{result.sequence}\n")
+
+            click.echo("Metrics:")
+            for key, value in result.metadata.get("metrics", {}).items():
+                click.echo(f"  - {key}: {value}")
+        else:
+            if output_format.lower() != "fasta":
+                raise ValueError("Non-FASTA output requires --template with v2 pipeline.")
+
+            # Get engine
+            optimizer = EngineRegistry.get(engine)
+
+            # Optimize
+            click.echo(f"Optimizing with {optimizer.name} v{optimizer.version}...")
+            result = optimizer.optimize(
+                sequence,
+                profile=profile,
+                scan_mode=scan_mode,
+                scan_include=scan_include_list,
+                scan_exclude=scan_exclude_list,
+            )
+
+            # Output results
+            if output:
+                with open(output, "w", encoding="utf-8") as f:
+                    f.write(result.sequence)
+                click.echo(f"Saved to: {output}")
+            else:
+                click.echo(f"\n{result.sequence}\n")
+
+            # Output metrics
+            click.echo("Metrics:")
+            for key, value in result.metrics.items():
+                click.echo(f"  - {key}: {value}")
+
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+if __name__ == "__main__":
+    cli()

factorforge/core/interfaces/__init__.py

@@ -0,0 +1,7 @@
+"""Core interfaces for extensibility"""
+
+from .exporter import Exporter
+from .optimizer import OptimizationResult, OptimizerEngine
+from .validator import Validator
+
+__all__ = ["OptimizerEngine", "OptimizationResult", "Validator", "Exporter"]

factorforge/core/interfaces/exporter.py

@@ -0,0 +1,13 @@
+"""Exporter interface"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Exporter(ABC):
+    @abstractmethod
+    def export(self, data: Any, format: str) -> str:
+        """Export data to the requested format."""
+        raise NotImplementedError

factorforge/core/interfaces/optimizer.py

@@ -0,0 +1,85 @@
+"""
+Optimizer Engine Interface
+
+Interface that all optimization engines (v1, v2, v3...) must implement
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class OptimizationResult:
+    """Optimization result"""
+
+    def __init__(
+        self,
+        sequence: str,
+        metrics: dict[str, float],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self.sequence = sequence
+        self.metrics = metrics
+        self.metadata = metadata or {}
+
+
+class OptimizerEngine(ABC):
+    """Abstract optimization engine interface"""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Engine name"""
+        ...
+
+    @property
+    @abstractmethod
+    def version(self) -> str:
+        """Engine version"""
+        ...
+
+    @abstractmethod
+    def optimize(
+        self,
+        sequence: str,
+        profile: str | None = None,
+        **kwargs: Any,
+    ) -> OptimizationResult:
+        """
+        Optimize a sequence
+
+        Args:
+            sequence: Input protein sequence
+            profile: Optimization profile (e.g., balanced, high_gc)
+            **kwargs: Additional parameters
+
+        Returns:
+            OptimizationResult
+        """
+        ...
+
+    @abstractmethod
+    def validate(self, sequence: str) -> bool:
+        """
+        Validate input
+
+        Args:
+            sequence: Sequence to validate
+
+        Returns:
+            bool: True if valid
+        """
+        ...
+
+    def get_metadata(self) -> dict[str, Any]:
+        """Engine metadata"""
+        return {
+            "name": self.name,
+            "version": self.version,
+            "supported_profiles": self.get_supported_profiles(),
+        }
+
+    def get_supported_profiles(self) -> list[str]:
+        """List of supported profiles"""
+        return []

factorforge/core/interfaces/validator.py

@@ -0,0 +1,9 @@
+"""Validator interface"""
+
+from abc import ABC, abstractmethod
+
+
+class Validator(ABC):
+    @abstractmethod
+    def validate(self, data: str) -> bool:
+        pass