Skip to main content

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 Python PyPI Bioconda CI codecov DOI Web App Buy Me A Coffee

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.6.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 · Roadmap


Quick Start

# Bioconda: Linux/macOS, or Ubuntu inside WSL on Windows
conda create -n factorforge-review --override-channels -c conda-forge -c bioconda --strict-channel-priority python=3.11 factorforge-cds
conda activate factorforge-review

# Via PyPI
pip install factorforge-cds

# Run optimization
factorforge optimize my_protein.fasta -o output.fasta

Or use the web app — no installation required.

Bioconda does not support native Windows. Use WSL for that installation route; see installation and reviewer checks for the tested version, platform limitations and installed-package smoke command. Local DP optimization needs no Neon database, GCP account or GPU.


Access Options

Method Description Link
Bioconda Linux/macOS; WSL on Windows Isolated installation
Web App No installation, demo & light use 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

Repository Structure

Experimental codon-distribution and evidence-ledger modules in the development checkout are scaffolds, not a validated laboratory policy or active learned recommendation service. Computational checks do not establish synthesis readiness or biological performance. Private inputs and collaborator packages must remain outside public repositories and dashboards.

The supported deterministic engines are the profile engine, stable DP v2, and the explicit DP v2.1.1 development candidate under:

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 and VALIDATION.md.


Citing

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

The v3.5.11 software archive and the accompanying computational preprint are separate citations. The preprint reports historical v3.2.0/v3.3.0 executions, not a benchmark of every later software release.


Maintainer

Mun-Kyu Kim (@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.

The extra pins eijex-db-core==0.1.2. Supply its approved wheel bundle using pip install --find-links PATH_TO_BUNDLE "factorforge-cds[postgres]"; the shared package is not assumed to have been published on PyPI. Standalone installation does not require it. 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.

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.

Disclaimer: FactorForge is provided for research purposes only. Outputs are computational and have not been experimentally validated.


Get in Touch

Testing status

The web UI labels watermark as disabled and distinguishes the sequence-only baseline from retained experimental structure-conditioned testing. The local reviewed workflow supports 1DP-only or paired 3DP mode. General 3DP/4DP web access is paused by default; local research availability is not a biological-performance claim. See web UI boundaries.

Experimental 3DP web access (paused by default)

The public form offers 1DP. General 3DP/4DP web access is paused pending evaluation and collaborator feedback. Research deployments require both a deliberate web build opt-in (ENABLE_EXPERIMENTAL_STRUCTURE_WEB) and server opt-in (FACTORFORGE_EXPERIMENTAL_3DP_ENABLED=true); these flags are availability controls, not authentication or research consent. Without the server flag, structure generation, recommendation and resolution requests fail with EXPERIMENTAL_STRUCTURE_DISABLED. Local experimental implementations are retained. See research boundaries.

Limits: 3–300 amino acids, structure content 250 KB, HTTP JSON body 1 MB. Both candidates use the configured codon reference, requested GC and canonical motif exclusions plus custom additions. Invalid inputs and infeasible candidates fail without a baseline fallback. Existing sequence-only settings and API requests remain supported. 3DP uses its explicit DP settings and does not apply Kozak, TpA, template or seed transformations. SOP checks are reported for both candidates; regeneration is manual and never silently changes mode. Watermark stays disabled.

This is stateless computational testing, with no external service dependencies or remote database recording. Those existing integrations remain available for later operational use. The structure file is not retained in the response or browser history; normal design results may be retained in local browser history. Submit only public-safe inputs. Structural conformity metrics are codon-weight proxies, not folding/expression measurements. These source changes are not deployed or a new package release.

Current public policy UI (2026-10-12)

Custom SOP management is paused. The built-in FactorForge default policy is applied; upload/export/preset/editing controls are hidden and disabled. Their code and previous browser configuration remain available for later reactivation through ENABLE_CUSTOM_SOP. Saved custom SOPs are ignored without deletion. 1DP remains active; general 3DP selection and API structure actions are disabled by default. Their retained research contract requires explicit deployment opt-in. This supersedes the earlier public SOP upload/export instructions.

Scientific web observations

Direct 1DP/3DP browser testing reports sense-CDS RNA motif scans and available initiation-window MFE in results, downloadable reports and local history. Structure confidence observations can suggest positions for explicit acceptance and review; unsupported inputs do not invent positions. These checks do not establish expression, yield or folding benefits. The default policy remains active and custom SOP management remains paused. See docs/experimental-structure.md for the API and measurement boundary.

Local reviewed structure file workflow

factorforge nbfold annotate and factorforge nbfold optimize provide the experimental local Phase A/B workflow for exact-match structure files and an explicit user review manifest. See NB-Fold documentation.

Web structure handling now requires exact-match uploaded PDB/mmCIF coordinates and explicit reviewed positions. Automatic external folding, artificial structure/confidence fallback, and auto-approval are disabled. Structure metrics are synthetic reconstruction checks; independent public-structure/DSSP validation remains open.

Experimental human-reference prototype

factorforge.engines.stemcell_3dp.StemCell3DPOptimizer is a local experimental interface using a generic human-frequency reference and provisional Eijex review criteria. It is not an MSC/iPSC-calibrated model or a laboratory-approved SOP. See prototype boundaries. It is not a new production web host.

Local research candidate: DP v2.2

The opt-in Python DPV220Optimizer shares the v2.1.1 DP core and adds reviewed position penalties. The experimental generic-human adapter uses this core; existing plant web/NB-Fold routes retain their prior objective. See the model card for usage, relaxation reporting and engineering validation boundaries. This is not an expression or folding claim.

Metadata

Release files for factorforge-cds 3.6.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for factorforge-cds 3.6.8
File Size Uploaded Provenance Actions
factorforge_cds-3.6.8.tar.gz 594.8 kB With provenance Details for factorforge_cds-3.6.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for factorforge-cds 3.6.8
File Interpreter ABI Platform Actions
factorforge_cds-3.6.8-py3-none-any.whl Python 3 none any Details for factorforge_cds-3.6.8-py3-none-any.whl

Total release size: 1.1 MB

Release files / factorforge_cds-3.6.8.tar.gz

Download URL factorforge_cds-3.6.8.tar.gz
Size 594.8 kB
Tags Source
SHA-256 checksum
How to use checksums
174876e79213ca3652c16311e96cb8bbb9b67129da7d83b81d8321affe4bddb6
BLAKE2b-256 checksum
How to use checksums
04fd8c4d7fd1d42ffcd2791f60f2ffecd37fad8c2ed7e2ff7b6cabae8b8b0b27
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / factorforge_cds-3.6.8-py3-none-any.whl

Download URL factorforge_cds-3.6.8-py3-none-any.whl
Size 539.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce7ed559972b947a5faaac72c5667daa2fb7dd8061b6a950fb4181f1b6c7f559
BLAKE2b-256 checksum
How to use checksums
2fadafbfdafbe9a4f3db3a3c95e216681d550d54e9bd6b9cd31ab463ca321924
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for factorforge-cds 3.6.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for factorforge_cds-3.6.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.6.8 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page