factorforge-cds 3.5.11__tar.gz → 3.5.12__tar.gz

{factorforge_cds-3.5.11/src/factorforge_cds.egg-info → factorforge_cds-3.5.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.5.11
+Version: 3.5.12
 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
@@ -34,6 +34,13 @@ Provides-Extra: ml
 Requires-Dist: transformers>=4.40; extra == "ml"
 Requires-Dist: torch>=2.0; extra == "ml"
 Requires-Dist: onnxruntime>=1.16; extra == "ml"
+Provides-Extra: acceleration
+Requires-Dist: pyahocorasick>=2.3.1; extra == "acceleration"
+Provides-Extra: benchmark
+Requires-Dist: dnachisel>=3.2.16; extra == "benchmark"
+Requires-Dist: scipy>=1.17; extra == "benchmark"
+Provides-Extra: ml-structure
+Requires-Dist: fair-esm>=2.0.0; extra == "ml-structure"
 Dynamic: license-file
 
 # FactorForge
@@ -43,6 +50,7 @@ Dynamic: license-file
 [![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/)
+[![Bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](https://anaconda.org/bioconda/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)
@@ -52,7 +60,7 @@ Dynamic: license-file
 
 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.11 uses independently versioned engines:
+FactorForge v3.5.12 uses independently versioned engines:
 
 | Generation | Engine | Version | Availability |
 |---|---|---:|---|
@@ -69,18 +77,31 @@ FactorForge v3.5.11 uses independently versioned engines:
 ## Quick Start
 
 ```bash
+# 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](https://factorforge.eijex.com)** — no installation required.
 
+Bioconda does not support native Windows. Use WSL for that installation route;
+see [installation and reviewer checks](docs/getting-started.md) 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](docs/getting-started.md#via-bioconda-recommended-for-bioinformatics) |
 | **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` |
@@ -134,10 +155,15 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.5.11 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.5.12 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 
+The [v3.5.11 software archive](https://doi.org/10.5281/zenodo.23631740)
+and the [accompanying computational preprint](https://doi.org/10.20944/preprints202610.3128.v1)
+are separate citations. The preprint reports historical v3.2.0/v3.3.0 executions,
+not a benchmark of every later software release.
+
 ---
 
 ## Maintainer
@@ -189,11 +215,11 @@ GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
 
 ## Testing status
 
-The web UI now labels watermark as disabled and distinguishes the sequence-only baseline from experimental structure-conditioned testing. The local approved workflow supports explicit 1DP-only or paired 3DP mode. 3DP availability is local research testing; it is not a new public optimization endpoint or a biological-performance claim. See [web UI boundaries](web/README.md).
+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](web/README.md).
 
-## Direct 3DP browser testing (unreleased)
+## Experimental 3DP web access (paused by default)
 
-The FactorForge form supports explicit 1DP/3DP selection. 3DP uploads a PDB/mmCIF file, selects chain and one-based file model order, and requires reviewed one-based protein positions. The selected observed chain must exactly match the complete protein; partial or homologous structures require the retained local reviewed mapping workflow. Direct requests use `/api/optimize` with `design_mode=paired_3dp` and `structure_context={content,format,chain,model,positions,positions_reviewed,target_adaptiveness,penalty_weight}`.
+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](docs/experimental-structure.md).
 
 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.
 
@@ -201,7 +227,7 @@ This is stateless computational testing, with no external service dependencies o
 
 ## 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/3DP mode selection and explicit structure inputs remain active. This supersedes the earlier public SOP upload/export instructions. Public API contracts are retained.
+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
 

{factorforge_cds-3.5.11 → factorforge_cds-3.5.12}/README.md

@@ -5,6 +5,7 @@
 [![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/)
+[![Bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](https://anaconda.org/bioconda/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)
@@ -14,7 +15,7 @@
 
 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.11 uses independently versioned engines:
+FactorForge v3.5.12 uses independently versioned engines:
 
 | Generation | Engine | Version | Availability |
 |---|---|---:|---|
@@ -31,18 +32,31 @@ FactorForge v3.5.11 uses independently versioned engines:
 ## Quick Start
 
 ```bash
+# 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](https://factorforge.eijex.com)** — no installation required.
 
+Bioconda does not support native Windows. Use WSL for that installation route;
+see [installation and reviewer checks](docs/getting-started.md) 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](docs/getting-started.md#via-bioconda-recommended-for-bioinformatics) |
 | **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` |
@@ -96,10 +110,15 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.5.11 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.5.12 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 
+The [v3.5.11 software archive](https://doi.org/10.5281/zenodo.23631740)
+and the [accompanying computational preprint](https://doi.org/10.20944/preprints202610.3128.v1)
+are separate citations. The preprint reports historical v3.2.0/v3.3.0 executions,
+not a benchmark of every later software release.
+
 ---
 
 ## Maintainer
@@ -151,11 +170,11 @@ GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
 
 ## Testing status
 
-The web UI now labels watermark as disabled and distinguishes the sequence-only baseline from experimental structure-conditioned testing. The local approved workflow supports explicit 1DP-only or paired 3DP mode. 3DP availability is local research testing; it is not a new public optimization endpoint or a biological-performance claim. See [web UI boundaries](web/README.md).
+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](web/README.md).
 
-## Direct 3DP browser testing (unreleased)
+## Experimental 3DP web access (paused by default)
 
-The FactorForge form supports explicit 1DP/3DP selection. 3DP uploads a PDB/mmCIF file, selects chain and one-based file model order, and requires reviewed one-based protein positions. The selected observed chain must exactly match the complete protein; partial or homologous structures require the retained local reviewed mapping workflow. Direct requests use `/api/optimize` with `design_mode=paired_3dp` and `structure_context={content,format,chain,model,positions,positions_reviewed,target_adaptiveness,penalty_weight}`.
+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](docs/experimental-structure.md).
 
 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.
 
@@ -163,7 +182,7 @@ This is stateless computational testing, with no external service dependencies o
 
 ## 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/3DP mode selection and explicit structure inputs remain active. This supersedes the earlier public SOP upload/export instructions. Public API contracts are retained.
+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
 

{factorforge_cds-3.5.11 → factorforge_cds-3.5.12}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=77.0.3", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.5.11"
+version = "3.5.12"
 description = "FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -45,6 +45,16 @@ ml = [
     "torch>=2.0",
     "onnxruntime>=1.16",
 ]
+acceleration = [
+    "pyahocorasick>=2.3.1",
+]
+benchmark = [
+    "dnachisel>=3.2.16",
+    "scipy>=1.17",
+]
+ml-structure = [
+    "fair-esm>=2.0.0",
+]
 
 [project.urls]
 Homepage = "https://factorforge.eijex.com"

{factorforge_cds-3.5.11 → factorforge_cds-3.5.12}/src/factorforge/analysis/metrics.py

@@ -408,18 +408,45 @@ def detect_repeats(sequence: str) -> list[dict[str, Any]]:
 
 
 def detect_forbidden_motifs(sequence: str, motifs: list[str]) -> list[dict[str, Any]]:
-    """Find all exact forbidden motif occurrences."""
+    """Find all exact forbidden motif occurrences.
+
+    Uses pyahocorasick C-automaton when available for O(N + M) single-pass scanning;
+    falls back transparently to pure Python string searching if unavailable.
+    """
     seq = _normalize_dna(sequence)
-    findings: list[dict[str, Any]] = []
-    for motif in motifs:
-        normalized = _normalize_dna(motif)
-        if not normalized:
-            continue
-        start = seq.find(normalized)
-        while start != -1:
-            findings.append({"start": start, "end": start + len(normalized), "motif": normalized})
-            start = seq.find(normalized, start + 1)
-    return findings
+    if not seq or not motifs:
+        return []
+
+    try:
+        import ahocorasick
+
+        A = ahocorasick.Automaton()
+        has_motif = False
+        for m in motifs:
+            norm = _normalize_dna(m)
+            if norm:
+                A.add_word(norm, norm)
+                has_motif = True
+        if not has_motif:
+            return []
+        A.make_automaton()
+
+        findings: list[dict[str, Any]] = []
+        for end_idx, norm in A.iter(seq):
+            start = end_idx - len(norm) + 1
+            findings.append({"start": start, "end": end_idx + 1, "motif": norm})
+        return sorted(findings, key=lambda x: (x["start"], x["end"]))
+    except ImportError:
+        findings = []
+        for motif in motifs:
+            normalized = _normalize_dna(motif)
+            if not normalized:
+                continue
+            start = seq.find(normalized)
+            while start != -1:
+                findings.append({"start": start, "end": start + len(normalized), "motif": normalized})
+                start = seq.find(normalized, start + 1)
+        return findings
 
 
 def detect_invalid_codons(sequence: str) -> list[dict[str, Any]]:

{factorforge_cds-3.5.11 → factorforge_cds-3.5.12}/src/factorforge/cli/main.py

@@ -998,8 +998,10 @@ def audit(sequence_fasta, reference_codon_profile, exclude_region, output):
 
 
 from factorforge.nbfold.cli import nbfold_cli
+from factorforge.cli.structure_cli import structure_cli
 
 cli.add_command(nbfold_cli)
+cli.add_command(structure_cli)
 
 
 if __name__ == "__main__":

factorforge_cds-3.5.12/src/factorforge/cli/structure_cli.py

@@ -0,0 +1,157 @@
+"""Click CLI subcommands for FactorForge structure intake, sidecars, and Mol* viewer integration."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from factorforge.structure.interpro_sidecar_fetcher import fetch_interpro_sidecar
+from factorforge.structure.uniprot_sidecar_fetcher import fetch_uniprot_sidecar
+from factorforge.structure.viewer_bridge import (
+    build_structure_position_mapping,
+    prepare_viewer_annotations,
+)
+
+
+@click.group("structure")
+def structure_cli() -> None:
+    """Structure intake, UniProt/InterPro automated sidecars, and Mol* viewer integration."""
+
+
+@structure_cli.command("fetch-uniprot")
+@click.option("--accession", "-a", required=True, help="UniProt accession (e.g. P21926).")
+@click.option("--sequence", "-s", default=None, help="Optional protein sequence to verify identity.")
+@click.option("--output", "-o", type=click.Path(path_type=Path), help="Output path for JSON sidecar.")
+@click.option("--cache-dir", type=click.Path(path_type=Path), default=None, help="Local cache directory.")
+def fetch_uniprot_cmd(
+    accession: str,
+    sequence: Optional[str],
+    output: Optional[Path],
+    cache_dir: Optional[Path],
+) -> None:
+    """Fetch and normalize UniProt experimental/curated features into FactorForge sidecar."""
+    result = fetch_uniprot_sidecar(
+        accession=accession,
+        target_protein_sequence=sequence,
+        cache_dir=cache_dir,
+    )
+    payload_str = json.dumps(result, indent=2)
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(payload_str, encoding="utf-8")
+        click.echo(f"UniProt sidecar saved to {output} (status: {result.get('status')})")
+    else:
+        click.echo(payload_str)
+
+
+@structure_cli.command("fetch-interpro")
+@click.option("--accession", "-a", required=True, help="UniProt accession for InterPro entry search.")
+@click.option("--sequence", "-s", required=True, help="Target protein sequence for coordinate bounds.")
+@click.option("--output", "-o", type=click.Path(path_type=Path), help="Output path for JSON sidecar.")
+@click.option("--cache-dir", type=click.Path(path_type=Path), default=None, help="Local cache directory.")
+def fetch_interpro_cmd(
+    accession: str,
+    sequence: str,
+    output: Optional[Path],
+    cache_dir: Optional[Path],
+) -> None:
+    """Fetch and normalize InterPro domain families into FactorForge sidecar."""
+    result = fetch_interpro_sidecar(
+        accession=accession,
+        target_protein_sequence=sequence,
+        cache_dir=cache_dir,
+    )
+    payload_str = json.dumps(result, indent=2)
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(payload_str, encoding="utf-8")
+        click.echo(f"InterPro sidecar saved to {output} (status: {result.get('status')})")
+    else:
+        click.echo(payload_str)
+
+
+@structure_cli.command("annotate")
+@click.option("--accession", "-a", required=True, help="UniProt accession (e.g. P21926).")
+@click.option("--structure-file", "--cif", type=click.Path(path_type=Path, exists=True), default=None, help="3D structure file (.cif, .mmcif, .pdb).")
+@click.option("--chain", default="A", help="Structure chain ID (default: A).")
+@click.option("--sequence", "-s", default=None, help="Optional protein sequence.")
+@click.option("--interpro/--no-interpro", default=True, help="Whether to fetch InterPro domains.")
+@click.option("--output", "-o", type=click.Path(path_type=Path), help="Output JSON path for consolidated annotations and viewer payload.")
+@click.option("--cache-dir", type=click.Path(path_type=Path), default=None, help="Cache directory.")
+def annotate_cmd(
+    accession: str,
+    structure_file: Optional[Path],
+    chain: str,
+    sequence: Optional[str],
+    interpro: bool,
+    output: Optional[Path],
+    cache_dir: Optional[Path],
+) -> None:
+    """Consolidate UniProt, InterPro, and 3D structure coordinates into verified Mol* viewer payload."""
+    click.echo(f"Fetching UniProt features for '{accession}'...")
+    uniprot_res = fetch_uniprot_sidecar(accession=accession, target_protein_sequence=sequence, cache_dir=cache_dir)
+
+    target_seq = sequence
+    if not target_seq and uniprot_res.get("status") == "AVAILABLE":
+        target_seq = uniprot_res.get("sequence", {}).get("value")
+
+    interpro_res = None
+    if interpro and target_seq:
+        click.echo(f"Fetching InterPro domains for '{accession}'...")
+        interpro_res = fetch_interpro_sidecar(accession=accession, target_protein_sequence=target_seq, cache_dir=cache_dir)
+
+    # Merge candidate regions
+    all_candidates = []
+    if uniprot_res.get("status") == "AVAILABLE":
+        all_candidates.extend(uniprot_res.get("candidate_regions", []))
+    if interpro_res and interpro_res.get("status") == "AVAILABLE":
+        all_candidates.extend(interpro_res.get("candidate_regions", []))
+
+    # Resolve 3D coordinates against structure if provided
+    position_mapping = None
+    if structure_file and target_seq:
+        click.echo(f"Mapping coordinates against structure '{structure_file.name}' chain '{chain}'...")
+        struct_text = structure_file.read_text(encoding="utf-8")
+        fmt = structure_file.suffix.lstrip(".").lower()
+        try:
+            position_mapping = build_structure_position_mapping(
+                protein_sequence=target_seq,
+                structure_content=struct_text,
+                format=fmt,
+                chain_id=chain,
+            )
+            click.echo(f"Successfully mapped {len(position_mapping)} residues to structure auth_seq_id.")
+        except Exception as exc:
+            click.echo(f"Warning: Structure coordinate mapping failed ({exc}). Falling back to unverified sequence indices.")
+
+    viewer_annotations = prepare_viewer_annotations(
+        {"candidate_regions": all_candidates},
+        auth_asym_id=chain,
+        position_mapping=position_mapping,
+    )
+
+    consolidated = {
+        "accession": accession,
+        "protein_length": len(target_seq) if target_seq else None,
+        "structure_file": str(structure_file) if structure_file else None,
+        "chain_id": chain,
+        "coordinate_mapping_verified": position_mapping is not None,
+        "uniprot": uniprot_res,
+        "interpro": interpro_res,
+        "candidate_regions_total": len(all_candidates),
+        "viewer_annotations": viewer_annotations,
+        "reviewed": False,  # Mandatory human review invariant
+        "epistemic_status": "UNVERIFIED_PUBLIC_CORPUS",
+        "biological_validation": "NOT_AVAILABLE",
+    }
+
+    out_json = json.dumps(consolidated, indent=2)
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(out_json, encoding="utf-8")
+        click.echo(f"Consolidated annotation report & viewer payload saved to {output}")
+    else:
+        click.echo(out_json)

{factorforge_cds-3.5.11 → factorforge_cds-3.5.12}/src/factorforge/registry/version_manifest.json

@@ -2,9 +2,9 @@
   "schema_version": "1.0",
   "product": {
     "name": "FactorForge",
-    "version": "3.5.11",
+    "version": "3.5.12",
     "release_status": "released",
-    "previous_stable_version": "3.5.10"
+    "previous_stable_version": "3.5.11"
   },
   "engines": {
     "profile": {

factorforge_cds-3.5.12/src/factorforge/structure/__init__.py

@@ -0,0 +1,45 @@
+"""Structure intake, annotation, and recommendation adapters for FactorForge."""
+
+from factorforge.structure.auto_annotator import (
+    CandidateRegion,
+    StructureRecommendationReport,
+    recommend_structure_pause_regions,
+)
+from factorforge.structure.esm_annotator import (
+    ESMRecommendationReport,
+    ESMStructureAnnotator,
+    recommend_esm_pause_regions,
+)
+from factorforge.structure.interpro_sidecar_fetcher import (
+    InterProSidecarFetcher,
+    fetch_interpro_raw_record,
+    fetch_interpro_sidecar,
+)
+from factorforge.structure.uniprot_sidecar_fetcher import (
+    UniProtSidecarFetcher,
+    fetch_uniprot_raw_record,
+    fetch_uniprot_sidecar,
+)
+from factorforge.structure.viewer_bridge import (
+    COLOR_PALETTE,
+    build_structure_position_mapping,
+    prepare_viewer_annotations,
+)
+
+__all__ = [
+    "CandidateRegion",
+    "StructureRecommendationReport",
+    "recommend_structure_pause_regions",
+    "ESMRecommendationReport",
+    "ESMStructureAnnotator",
+    "recommend_esm_pause_regions",
+    "UniProtSidecarFetcher",
+    "fetch_uniprot_raw_record",
+    "fetch_uniprot_sidecar",
+    "InterProSidecarFetcher",
+    "fetch_interpro_raw_record",
+    "fetch_interpro_sidecar",
+    "COLOR_PALETTE",
+    "build_structure_position_mapping",
+    "prepare_viewer_annotations",
+]