Metadata-Version: 2.4
Name: factorforge-cds
Version: 3.5.4
Summary: FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex.
Author-email: Eijex <eijex.lab@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://factorforge.eijex.com
Project-URL: Repository, https://github.com/eijex/factorforge-cds
Project-URL: Issues, https://github.com/eijex/factorforge-cds/issues
Keywords: codon optimization,CDS design,synthetic biology,bioinformatics,Nicotiana benthamiana,Nicotiana tabacum,Tobacco BY-2,constraint optimization,dynamic programming
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.81
Requires-Dist: requests>=2.31
Requires-Dist: click>=8.4.1
Requires-Dist: pydantic>=2.0
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
Requires-Dist: sqlalchemy>=2.0; extra == "postgres"
Provides-Extra: dev
Requires-Dist: jsonschema>=4.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.15.18; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Provides-Extra: ml
Requires-Dist: transformers>=4.40; extra == "ml"
Requires-Dist: torch>=2.0; extra == "ml"
Requires-Dist: onnxruntime>=1.16; extra == "ml"
Dynamic: license-file

# FactorForge

**Open-source constraint-based CDS design and pre-synthesis sequence review for plant CDS workflows, with primary support for *Nicotiana benthamiana* (Tobacco BY-2: experimental).**

[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![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.20407330.svg)](https://doi.org/10.5281/zenodo.20407330)
[![Web App](https://img.shields.io/badge/web-factorforge.eijex.com-brightgreen.svg)](https://factorforge.eijex.com)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow?style=flat&logo=buy-me-a-coffee)](https://www.buymeacoffee.com/eijex)


FactorForge performs deterministic CDS design with CAI/GC metrics, PolyA-signal screening, and Golden Gate/MoClo-aware checks. It is positioned as a pre-synthesis review harness: it helps teams generate reproducible CDS candidates, inspect assembly-relevant sequence constraints, and package design metadata before downstream synthesis, cloning, or experimental review. Primary support: *N. benthamiana* (agroinfiltration). Experimental host context: Tobacco BY-2 (`--host by2`).

FactorForge v3.5.4 uses independently versioned engines:

| Generation | Engine | Version | Availability |
|---|---|---:|---|
| Gen 1 | Rule/profile | 1.0.0 | Stable, public |
| Gen 2 | DP v2 | 2.0.1 | Stable, public default feasibility path |
| Gen 2 | DP v2.1.1 | 2.1.1 | Explicit local-guard path; computational evidence only |
| Gen 3 | sLLM Hybrid | 0.2.0-preview.1 | Feature-gated constrained-generation research preview |
| Rescue | Adaptive partial DP | 1.0.0 | Exact suffix rescue conditioned on a verified prefix |

**→ [Full Documentation](https://eijex.github.io/factorforge-cds/)** · **[Roadmap](https://eijex.github.io/factorforge-cds/roadmap/)**

---

## 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 deterministic engines are the profile engine, stable DP v2, and
the explicit DP v2.1.1 development candidate under:

```text
src/factorforge/engines/profile/
src/factorforge/engines/dp_v2.py
src/factorforge/engines/dp_v2_1_1.py
src/factorforge/engines/sllm/
src/factorforge/discovery/
```

DP v2.1.1 adds an exact active-layer 5′ GC guard and Aho-Corasick rejection of
homopolymers of 6 nt or longer to the v2.1 initiation-aware objective. It emits
local-composition metrics and, when ViennaRNA and sufficient transcript context
are available, a separately evaluated 5′ MFE value. It is not the default; its
single-target calibration does not establish holdout generalization or biological
performance.

The v3.5.x discovery-slate surface generates versioned Top-K research candidates,
applies a shared deterministic hard-constraint filter, and records generator and
fallback lineage. The sLLM path is disabled by default. A partial-DP rescue solves
an exact suffix conditioned on the retained prefix; it is not a claim of global
optimality and does not establish biological performance.

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. These checks support reviewability and reproducibility; they do not guarantee expression, yield, synthesis acceptance, folding, glycosylation, regulatory approval, or downstream biological performance. See [Validation](https://eijex.github.io/factorforge-cds/validation/) and [VALIDATION.md](VALIDATION.md).

---

## Citing

```
FactorForge v3.5.4 (2026). Open-source constraint-based CDS design and sequence review.
Eijex. https://github.com/eijex/factorforge-cds
```

---

## Maintainer

Mun-Kyu Kim ([@eijex](https://github.com/eijex))

## Optional PostgreSQL support

FactorForge design, CLI, Python API, and file export do not require a database.
PostgreSQL persistence is an explicit Eijex integration path for retaining shared
campaign and candidate identities; it is not enabled by default.

Install `pip install "factorforge-cds[postgres]"` only when using that integration.
The deployment must also provide a compatible `eijex-db-core` package and set
`FACTORFORGE_DATABASE_URL`. FactorForge contains no default database credentials and
does not silently fall back to another backend. See [Persistence](docs/persistence.md).

Explicit local SQLite research checkpoints in `factorforge.db.connector` remain a
separate local-only utility and are not the shared DBTL system of record.

## 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

- **Sponsor** — Support our research via [GitHub Sponsors](https://github.com/sponsors/eijex) or [PayPal](https://paypal.me/munkyukim)
- **Docs** — [eijex.github.io/factorforge-cds](https://eijex.github.io/factorforge-cds/)
- **Wet-lab Feedback** — Public-safe feedback summaries are welcome via [Share Wet-lab Feedback (GitHub)](https://github.com/eijex/factorforge-cds/issues/new?template=wet_lab_result.yml). Do not submit raw sequences, confidential construct details, internal batch IDs, patient data, private contact information, exact process parameters, or confidential partner/customer data. Email `eijex.lab@gmail.com` for private or sensitive summaries. See [VALIDATION.md](VALIDATION.md) before submitting.
- **Sequence Policy Profiles** — FactorForge applies the sequence-review policy
  chosen by the user; it does not define or approve a laboratory SOP. The web
  app provides an illustrative YAML example and active-profile export.
  Sequence-free, non-confidential suggestions can be submitted through the
  public policy-template form; use `eijex.lab@gmail.com` for private or
  laboratory-specific profiles. See the [sequence policy boundary](docs/sequence-policy.md).
- **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)
- **Eijex MCP** — [mcp.eijex.com](https://mcp.eijex.com)
- **Lab** — [www.eijex.com](https://www.eijex.com)

