Deploy mRNA Design Studio (Docker SDK)

.dockerignore

@@ -0,0 +1,13 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+.git/
+.claude/
+.env
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+demo/mrna_parts.db

.env.example

@@ -0,0 +1,22 @@
+# ─────────────────────────────────────────────────────────────────────────────
+#  mRNA Design Studio — environment configuration
+#
+#  Copy this file to .env and fill in the values you need.
+#  The app loads .env automatically via python-dotenv.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Password protection (pick ONE) ──────────────────────────────────────────
+
+# Option A: single shared password (any username accepted at login)
+MRNA_STUDIO_PASSWORD=changeme
+
+# Option B: multiple users (JSON — overrides MRNA_STUDIO_PASSWORD if set)
+# MRNA_STUDIO_USERS={"alice": "pass1", "bob": "pass2"}
+
+# ── Session cookie secret (change in production!) ───────────────────────────
+MRNA_STUDIO_COOKIE_SECRET=replace-with-a-random-string
+
+# ── Server ───────────────────────────────────────────────────────────────────
+# PORT=5007            # overridden by Railway / Render automatically
+# HOST=0.0.0.0         # bind to all interfaces (required in containers)
+# MRNA_STUDIO_RELOAD=1 # set to 1 to enable hot-reload during development

.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Panel/Bokeh
+*.html
+!docs/**/*.html
+
+# Logs
+*.log
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Temporary files
+*.tmp
+.cache/
+
+# Export files
+worklist_export.csv
+
+# Environment / secrets
+.env

Dockerfile

@@ -0,0 +1,42 @@
+# ─────────────────────────────────────────────────────────────────────────────
+#  mRNA Design Studio — production container
+#
+#  Build:  docker build -t mrna-studio .
+#  Run:    docker run -p 5007:5007 -e MRNA_STUDIO_PASSWORD=changeme mrna-studio
+# ─────────────────────────────────────────────────────────────────────────────
+FROM python:3.13-slim AS base
+
+# Prevent Python from buffering stdout/stderr (makes logs visible immediately)
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# ── Install system deps (needed by some bioinformatics packages) ─────────────
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends gcc g++ libpq-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+# ── Install Python deps (cached layer — only rebuilds when requirements change)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ── Copy application code ────────────────────────────────────────────────────
+COPY . .
+
+# ── Runtime ──────────────────────────────────────────────────────────────────
+# Railway, Render, Fly etc. set $PORT automatically
+ENV PORT=5007 \
+    HOST=0.0.0.0
+
+# Hugging Face Spaces runs the container as UID 1000 (non-root). Point HOME and
+# library cache dirs at /tmp (world-writable) so Panel/Bokeh/matplotlib can
+# write caches without permission errors.
+ENV HOME=/tmp \
+    XDG_CACHE_HOME=/tmp/.cache \
+    MPLCONFIGDIR=/tmp/matplotlib \
+    NUMBA_CACHE_DIR=/tmp/numba
+
+EXPOSE ${PORT}
+
+CMD ["python", "-m", "ui.app"]

MODELS_ADDED.md

@@ -0,0 +1,177 @@
+# mRNA Scoring Models - Implementation Summary
+
+I've successfully added two mRNA scoring models to the core package as requested.
+
+## Models Added
+
+### 1. **RNAstructure MFE Scorer** (`models/rna_structure_scorer.py`)
+
+**What it does**: Predicts the minimum free energy (MFE) of mRNA secondary structure to assess translation efficiency.
+
+**Key features**:
+- Uses ViennaRNA when available for accurate MFE calculation
+- Falls back to GC-content based proxy scoring when ViennaRNA is not installed
+- Score range: 0-100 (optimal: 40-70)
+- Higher scores indicate stronger secondary structures
+
+**Scientific basis**: Based on ViennaRNA thermodynamic calculations (Lorenz et al., 2011)
+
+---
+
+### 2. **mRNA Stability Scorer** (`models/mrna_stability_scorer.py`)
+
+**What it does**: Composite stability prediction combining five established mRNA design principles.
+
+**Scoring components**:
+1. **GC Content** (30% weight) - Optimal range: 50-60%
+2. **Codon Adaptation Index** (25% weight) - Codon optimization
+3. **Homopolymer Detection** (20% weight) - Penalizes long identical runs
+4. **5' UTR Structure** (15% weight) - Moderate stability preferred
+5. **Kozak Consensus** (10% weight) - Translation initiation strength
+
+**Key features**:
+- Score range: 0-100 (70+ = excellent, 40-70 = acceptable, <40 = poor)
+- Configurable for different organisms (default: human)
+- Individual component scores accessible for detailed analysis
+
+**Scientific basis**:
+- Kozak sequence analysis (Mauro & Edelman, 2002)
+- CAI methodology (Sharp & Li, 1987)
+- mRNA stability research (Presnyak et al., 2015)
+
+---
+
+## Files Created
+
+```
+models/
+├── rna_structure_scorer.py    # RNAstructure MFE model
+├── mrna_stability_scorer.py   # mRNA Stability composite model
+├── __init__.py                # Updated to export new models
+└── README.md                  # Full documentation
+
+tests/
+└── test_models.py             # Added comprehensive tests for both models
+
+demo/
+└── demo_models.py             # Demo script showing usage
+```
+
+---
+
+## Testing Results
+
+All tests pass successfully:
+
+```bash
+$ pytest tests/test_models.py::TestRNAStructureMFEScorer -v
+$ pytest tests/test_models.py::TestmRNAStabilityScorer -v
+
+8 passed in 0.13s ✓
+```
+
+---
+
+## Usage Example
+
+```python
+from core.models.sequence import mRNASequence
+from models import RNAStructureMFEScorer, mRNAStabilityScorer
+
+# Create a sequence
+seq = mRNASequence(
+    name="my_mrna",
+    source="local",
+    five_prime_utr="GTTGCTCCTTCGGGCCTGTGGCGGCT",
+    kozak="GCCACCATGG",
+    cds="ATGGTGAGCAAGGGCGAGGAG...",
+)
+
+# Score with MFE model
+mfe_scorer = RNAStructureMFEScorer()
+mfe_score = mfe_scorer.score(seq)
+print(f"MFE Score: {mfe_score:.1f}/100")
+
+# Score with Stability model
+stability_scorer = mRNAStabilityScorer(organism="human")
+stability_score = stability_scorer.score(seq)
+print(f"Stability Score: {stability_score:.1f}/100")
+```
+
+---
+
+## Demo Output
+
+Run the demo to see both models in action:
+
+```bash
+$ PYTHONPATH=. .venv/bin/python demo/demo_models.py
+```
+
+Sample output:
+```
+RNAstructure MFE Scorer
+Score: 64.2/100
+Interpretation: Optimal structure for translation ✓
+
+mRNA Stability Scorer
+Overall Score: 76.2/100
+Interpretation: Excellent design ✓
+
+  Component Breakdown:
+    GC Content (30%):   100.0/100
+    CAI (25%):          63.9/100
+    Homopolymers (20%): 65.0/100
+    5' UTR (15%):       61.5/100
+    Kozak (10%):        80.0/100
+```
+
+---
+
+## ModelRegistry Integration
+
+Both models are compatible with the existing ModelRegistry system:
+
+```python
+from models import ModelRegistry
+
+registry = ModelRegistry()
+registry._register(RNAStructureMFEScorer(), "scoring", "builtin", "")
+registry._register(mRNAStabilityScorer(), "scoring", "builtin", "")
+
+# Batch score sequences
+results = registry.run_scoring("mRNA Stability", sequences)
+```
+
+---
+
+## Dependencies
+
+**Required**:
+- Core Python libraries (no additional dependencies for basic functionality)
+
+**Optional** (for enhanced features):
+- `ViennaRNA` - For accurate RNA secondary structure prediction
+- `BioPython` - For advanced codon usage analysis
+
+Both models degrade gracefully when optional dependencies are missing.
+
+---
+
+## Next Steps
+
+To integrate these models into the UI sidebar:
+
+1. Update `ui/components/sidebar.py` to show loaded models
+2. Implement model loading UI in the "⊕ Load Model" button handler
+3. Auto-register built-in models on app startup
+4. Add model scoring to the Worklist view
+
+---
+
+## References
+
+- **ViennaRNA**: Lorenz et al. (2011). Algorithms for Molecular Biology, 6:26
+- **Kozak**: Mauro & Edelman (2002). PNAS, 99(19):12031-12036
+- **CAI**: Sharp & Li (1987). Nucleic Acids Research, 15(3):1281-1295
+- **mRNA Stability**: Presnyak et al. (2015). Cell, 160(6):1111-1124

Makefile

@@ -0,0 +1,155 @@
+# ─────────────────────────────────────────────────────────────────────────────
+#  mRNA Design Studio — Makefile
+#
+#  Quick start (from scratch, no Python required):
+#    make setup        # one-time: installs uv, Python 3.13, and all deps
+#    make run          # start the app → http://localhost:5007
+# ─────────────────────────────────────────────────────────────────────────────
+.PHONY: help setup run run-debug run-secure kill restart clean test lint \
+        db-up db-down db-status docker-build docker-run
+
+# ── OS detection ──────────────────────────────────────────────────────────────
+# $(OS) is set to "Windows_NT" on Windows by the shell; empty on macOS/Linux.
+ifeq ($(OS),Windows_NT)
+    VENV_BIN := .venv/Scripts
+else
+    VENV_BIN := .venv/bin
+endif
+
+PYTHON  := $(VENV_BIN)/python
+PORT    := 5007
+URL     := http://localhost:$(PORT)
+COMPOSE := docker compose -f demo/docker-compose.yml
+
+# Where uv installs itself by default (used right after first install,
+# before the user's shell has reloaded PATH).
+UV_HOME := $(or $(XDG_BIN_HOME),$(HOME)/.local/bin)
+UV      := $(shell command -v uv 2>/dev/null || echo "$(UV_HOME)/uv")
+
+# ── Default target ────────────────────────────────────────────────────────────
+help: ## Show available commands
+	@echo ""
+	@echo "  mRNA Design Studio"
+	@echo "  ===================="
+	@echo ""
+	@echo "  First time?  Run:  make setup"
+	@echo "  Then:              make run     →  $(URL)"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+	@echo ""
+
+# ── Setup ─────────────────────────────────────────────────────────────────────
+setup: _ensure-uv _ensure-venv _install-deps ## One-time setup: install Python, create venv, install deps
+	@echo ""
+	@echo "  Setup complete!"
+	@echo "  Run 'make run' to start the app."
+	@echo ""
+
+_ensure-uv:
+	@command -v uv >/dev/null 2>&1 && exit 0; \
+	if [ -x "$(UV_HOME)/uv" ]; then exit 0; fi; \
+	echo "Installing uv (fast Python package manager)..."; \
+	curl -LsSf https://astral.sh/uv/install.sh | sh 2>/dev/null \
+		|| { echo "curl failed — trying wget..."; \
+		     wget -qO- https://astral.sh/uv/install.sh | sh; }; \
+	if ! command -v uv >/dev/null 2>&1 && [ ! -x "$(UV_HOME)/uv" ]; then \
+		echo ""; \
+		echo "  ERROR: uv installed but not found in PATH."; \
+		echo "  Restart your terminal, then re-run:  make setup"; \
+		echo ""; \
+		exit 1; \
+	fi
+
+_ensure-venv:
+	@if [ ! -d ".venv" ]; then \
+		echo "Creating virtual environment..."; \
+		if command -v $(UV) >/dev/null 2>&1; then \
+			$(UV) venv .venv --python 3.13; \
+		else \
+			python3 -m venv .venv; \
+		fi; \
+	fi
+
+_install-deps:
+	@echo "Installing dependencies..."
+	@if command -v $(UV) >/dev/null 2>&1; then \
+		$(UV) pip install -r requirements-dev.txt --python $(PYTHON) --quiet; \
+	else \
+		$(PYTHON) -m pip install -r requirements-dev.txt --quiet; \
+	fi
+
+# ── App ───────────────────────────────────────────────────────────────────────
+run: _check-venv ## Start the app → http://localhost:5007
+	$(PYTHON) -m ui.app
+
+run-secure: _check-venv ## Start with password protection (.env must exist)
+	@if [ ! -f .env ]; then \
+		echo ""; \
+		echo "  No .env file found. Copy the template first:"; \
+		echo "    cp .env.example .env"; \
+		echo "  Then set MRNA_STUDIO_PASSWORD in .env"; \
+		echo ""; \
+		exit 1; \
+	fi
+	MRNA_STUDIO_RELOAD=1 $(PYTHON) -m ui.app
+
+run-debug: _check-venv ## Start with DEBUG-level logging
+	LOG_LEVEL=DEBUG $(PYTHON) -c "\
+		import logging, sys, os; \
+		logging.basicConfig(level=getattr(logging, os.environ.get('LOG_LEVEL','INFO')), \
+			format='%(asctime)s [%(levelname)s] %(name)s: %(message)s', datefmt='%H:%M:%S', stream=sys.stderr); \
+		from ui.app import main; main()"
+
+kill: ## Stop the app if it's running
+ifeq ($(OS),Windows_NT)
+	@powershell -Command \
+		"Get-NetTCPConnection -LocalPort $(PORT) -ErrorAction SilentlyContinue \
+		 | ForEach-Object { Stop-Process -Id $$_.OwningProcess -Force }" 2>/dev/null \
+		|| echo "Nothing running on port $(PORT)"
+else
+	@lsof -ti:$(PORT) | xargs kill -9 2>/dev/null || echo "Nothing running on port $(PORT)"
+endif
+
+restart: kill run ## Kill + restart the app
+
+# ── Dev tools ─────────────────────────────────────────────────────────────────
+test: _check-venv ## Run the test suite
+	$(PYTHON) -m pytest tests/ -v
+
+lint: _check-venv ## Lint with ruff
+	$(PYTHON) -m ruff check .
+
+clean: ## Remove the virtual environment
+	rm -rf .venv
+	@echo "Removed .venv — run 'make setup' to recreate."
+
+# ── Database ──────────────────────────────────────────────────────────────────
+db-up: ## Start the demo PostgreSQL database
+	$(COMPOSE) up -d
+	@echo "Waiting for PostgreSQL to be ready..."
+	@until docker exec mrna_studio_demo_db pg_isready -U demo_user -d mrna_studio >/dev/null 2>&1; do sleep 1; done
+	@echo "PostgreSQL is ready on localhost:5432"
+
+db-down: ## Stop the demo database
+	$(COMPOSE) down
+
+db-status: ## Check database container status
+	@docker ps --filter name=mrna_studio_demo_db --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" 2>/dev/null || echo "Container not running"
+
+# ── Docker (production) ──────────────────────────────────────────────────────
+docker-build: ## Build production Docker image
+	docker build -t mrna-studio .
+
+docker-run: ## Run container with .env file (password-protected)
+	docker run --rm -p 5007:5007 --env-file .env mrna-studio
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+_check-venv:
+	@if [ ! -d ".venv" ]; then \
+		echo ""; \
+		echo "  No virtual environment found."; \
+		echo "  Run 'make setup' first."; \
+		echo ""; \
+		exit 1; \
+	fi

Procfile

@@ -0,0 +1 @@
+web: python -m ui.app

README.md

@@ -1,10 +1,59 @@
 ---
-title: Mrna Design Studio
-emoji: 🏢
-colorFrom: red
-colorTo: pink
+title: mRNA Design Studio
+emoji: 🧬
+colorFrom: green
+colorTo: blue
 sdk: docker
+app_port: 5007
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# mRNA Design Studio
+
+A browser-based workbench for designing, analyzing, and assembling mRNA sequences. Import sequence data from CSV files or PostgreSQL databases, run codon-usage and structural analyses, score sequences with pluggable models, assemble inserts into plasmid backbones with QC checks, and export results — all from a single reactive UI powered by Panel.
+
+- **Import Data** — load sequences from CSV/Excel files or PostgreSQL, map columns to the mRNA model, and organize into worklists
+- **Model Repository** — register local Python scoring/generative models or remote API endpoints
+- **Worklist** — inspect, analyze (GC%, CAI, homopolymers, restriction sites), score with loaded models, and export sequences as CSV
+- **Parts Workshop** — browse and compose reusable sequence parts (UTRs, Kozak, CDS, PolyA)
+- **Assemble Plasmid** — pick a backbone and cloning strategy, run QC, and export assembled constructs
+- **Generate Sequences** — create optimized mRNA variants with configurable generation settings
+
+## Getting Started
+
+The only prerequisite is a terminal with `make` and `curl` (both come pre-installed on macOS; on Windows use Git Bash or WSL). No Python install is required — the setup command handles everything.
+
+```bash
+git clone <repo-url> && cd mrna_design_studio
+
+make setup   # installs uv, Python 3.13, and all dependencies (~1 min)
+make run     # starts the app at http://localhost:5007
+```
+
+Run `make` by itself to see every available command:
+
+```
+make help
+
+  setup          One-time setup: install Python, create venv, install deps
+  run            Start the app
+  run-debug      Start with DEBUG-level logging
+  kill           Stop the app if it's running
+  restart        Kill + restart the app
+  test           Run the test suite
+  lint           Lint with ruff
+  clean          Remove the virtual environment
+  db-up          Start the demo PostgreSQL database (requires Docker)
+  db-down        Stop the demo database
+  db-status      Check database container status
+```
+
+### Demo database (optional)
+
+A Docker Compose file is included to spin up a PostgreSQL instance pre-loaded with sample mRNA sequences:
+
+```bash
+make db-up      # start the container
+make run        # connect using the pre-filled credentials on the Import Data tab
+make db-down    # stop when done
+```

core/analysis/analyzer.py

@@ -0,0 +1,276 @@
+"""
+SequenceAnalyzer — main analysis entry point.
+
+Runs all analysis modules against an mRNASequence and returns a
+structured AnalysisReport. Results are cached on the sequence object
+so repeated calls are cheap.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+
+from core.models.sequence import mRNASequence
+from core.analysis.gc_content import (
+    gc_percent,
+    gc_sliding_window,
+    gc_by_codon_position,
+)
+from core.analysis.cai import calculate_cai, codon_usage_report, CODON_TABLES
+from core.analysis.homopolymers import detect_homopolymers, HomopolymerRun
+from core.analysis.restriction_sites import (
+    scan_restriction_sites,
+    RestrictionSiteHit,
+    COMMON_ENZYMES,
+)
+from core.analysis.kozak import check_kozak, KozakResult
+from core.analysis.structure import predict_structure, StructureResult
+
+
+@dataclass
+class AnalysisReport:
+    """All analysis results for a single mRNASequence."""
+    sequence_id: str
+    sequence_name: str
+    sequence_length: int
+
+    # GC content
+    gc_percent_global: float = 0.0
+    gc_sliding_positions: Optional[np.ndarray] = None  # centre positions
+    gc_sliding_values: Optional[np.ndarray] = None     # GC% per window
+    gc_by_codon_position: Optional[Dict[str, float]] = None
+
+    # Codon Adaptation Index
+    cai: Optional[float] = None
+    cai_organism: Optional[str] = None
+    codon_usage: Optional[Dict[str, int]] = None
+
+    # Homopolymers
+    homopolymer_runs: List[HomopolymerRun] = field(default_factory=list)
+    homopolymer_count: int = 0
+    longest_homopolymer: int = 0
+
+    # Restriction sites
+    restriction_hits: Dict[str, List[RestrictionSiteHit]] = field(default_factory=dict)
+    restriction_enzymes_present: List[str] = field(default_factory=list)
+
+    # Start / stop codon validation
+    has_start_codon: Optional[bool] = None
+    has_stop_codon: Optional[bool] = None
+    stop_codon: Optional[str] = None
+    in_frame: Optional[bool] = None
+
+    # Kozak context
+    kozak: Optional[KozakResult] = None
+
+    # Secondary structure (ViennaRNA)
+    structure: Optional[StructureResult] = None
+
+    # Errors / warnings generated during analysis
+    warnings: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sequence_id": self.sequence_id,
+            "sequence_name": self.sequence_name,
+            "sequence_length": self.sequence_length,
+            "gc_content": self.gc_percent_global,
+            "gc_percent_global": self.gc_percent_global,
+            "gc_by_codon_position": self.gc_by_codon_position,
+            "cai": self.cai,
+            "cai_organism": self.cai_organism,
+            "homopolymer_count": self.homopolymer_count,
+            "longest_homopolymer": self.longest_homopolymer,
+            "restriction_site_count": len(self.restriction_enzymes_present),
+            "restriction_enzymes_present": self.restriction_enzymes_present,
+            "has_start_codon": self.has_start_codon,
+            "has_stop_codon": self.has_stop_codon,
+            "stop_codon": self.stop_codon,
+            "in_frame": self.in_frame,
+            "kozak_score": self.kozak.score if self.kozak else None,
+            "kozak_strength": self.kozak.strength if self.kozak else None,
+            "mfe": self.structure.mfe if self.structure else None,
+            "warnings": self.warnings,
+        }
+
+
+class SequenceAnalyzer:
+    """
+    Runs analysis modules against mRNASequence objects.
+
+    Results are cached inside the sequence's _analysis_cache dict
+    (keyed by analysis type) so re-running is a cache lookup.
+    """
+
+    def __init__(
+        self,
+        gc_window: int = 100,
+        gc_step: int = 1,
+        homopolymer_min_run: int = 5,
+        restriction_enzymes: Optional[List[str]] = None,
+        cai_organism: str = "human",
+        cai_custom_table: Optional[Dict[str, float]] = None,
+    ) -> None:
+        self.gc_window = gc_window
+        self.gc_step = gc_step
+        self.homopolymer_min_run = homopolymer_min_run
+        self.restriction_enzymes = restriction_enzymes or list(COMMON_ENZYMES.keys())
+        self.cai_organism = cai_organism
+        self.cai_custom_table = cai_custom_table
+
+    # ── Individual analysis methods ─────────────────────────────────────────
+
+    def analyze_gc(self, sequence: str) -> Dict[str, Any]:
+        positions, values = gc_sliding_window(sequence, self.gc_window, self.gc_step)
+        return {
+            "gc_percent_global": gc_percent(sequence),
+            "gc_sliding_positions": positions,
+            "gc_sliding_values": values,
+        }
+
+    def analyze_cai(self, cds: str) -> Dict[str, Any]:
+        try:
+            cai_value = calculate_cai(cds, self.cai_organism, self.cai_custom_table)
+            usage = codon_usage_report(cds)
+            return {
+                "cai": cai_value,
+                "cai_organism": self.cai_custom_table and "custom" or self.cai_organism,
+                "codon_usage": usage,
+            }
+        except Exception as e:
+            return {"cai": None, "cai_organism": None, "codon_usage": None, "error": str(e)}
+
+    def analyze_homopolymers(self, sequence: str) -> Dict[str, Any]:
+        runs = detect_homopolymers(sequence, self.homopolymer_min_run)
+        return {
+            "homopolymer_runs": runs,
+            "homopolymer_count": len(runs),
+            "longest_homopolymer": max((r.length for r in runs), default=0),
+        }
+
+    def analyze_restriction_sites(self, sequence: str) -> Dict[str, Any]:
+        hits = scan_restriction_sites(sequence, self.restriction_enzymes)
+        return {
+            "restriction_hits": hits,
+            "restriction_enzymes_present": list(hits.keys()),
+        }
+
+    def validate_cds(self, cds: str) -> Dict[str, Any]:
+        seq = cds.upper().replace("U", "T")
+        start_codons = {"ATG"}
+        stop_codons = {"TAA", "TAG", "TGA"}
+        has_start = seq[:3] in start_codons if len(seq) >= 3 else False
+        stop = seq[-3:] if len(seq) >= 3 else ""
+        has_stop = stop in stop_codons
+        in_frame = len(seq) % 3 == 0
+        return {
+            "has_start_codon": has_start,
+            "has_stop_codon": has_stop,
+            "stop_codon": stop if has_stop else None,
+            "in_frame": in_frame,
+        }
+
+    def analyze_kozak(self, sequence: str) -> Dict[str, Any]:
+        try:
+            result = check_kozak(sequence)
+            return {"kozak": result}
+        except ValueError as e:
+            return {"kozak": None, "kozak_warning": str(e)}
+
+    def analyze_structure(self, sequence: str) -> Dict[str, Any]:
+        result = predict_structure(sequence)
+        return {"structure": result}
+
+    # ── Full report ─────────────────────────────────────────────────────────
+
+    def run_full_analysis(
+        self,
+        seq: mRNASequence,
+        include_structure: bool = True,
+        force_rerun: bool = False,
+    ) -> AnalysisReport:
+        """
+        Run all analysis modules against seq and return an AnalysisReport.
+
+        Results are cached in seq._analysis_cache. Set force_rerun=True
+        to bypass the cache.
+        """
+        cache_key = "full_analysis"
+        if not force_rerun and cache_key in seq._analysis_cache:
+            return seq._analysis_cache[cache_key]  # type: ignore[return-value]
+
+        full_seq = seq.assembled_sequence
+        warnings: List[str] = []
+
+        report = AnalysisReport(
+            sequence_id=seq.id,
+            sequence_name=seq.name,
+            sequence_length=len(full_seq),
+        )
+
+        # GC content — run on full sequence
+        gc_data = self.analyze_gc(full_seq)
+        report.gc_percent_global = gc_data["gc_percent_global"]
+        report.gc_sliding_positions = gc_data["gc_sliding_positions"]
+        report.gc_sliding_values = gc_data["gc_sliding_values"]
+
+        # GC by codon position — only if CDS available
+        if seq.cds and len(seq.cds) % 3 == 0:
+            try:
+                report.gc_by_codon_position = gc_by_codon_position(seq.cds)
+            except Exception as e:
+                warnings.append(f"GC by codon position failed: {e}")
+
+        # CAI — only on CDS
+        if seq.cds:
+            cai_data = self.analyze_cai(seq.cds)
+            report.cai = cai_data.get("cai")
+            report.cai_organism = cai_data.get("cai_organism")
+            report.codon_usage = cai_data.get("codon_usage")
+            if "error" in cai_data:
+                warnings.append(f"CAI error: {cai_data['error']}")
+
+            # CDS validation
+            cds_data = self.validate_cds(seq.cds)
+            report.has_start_codon = cds_data["has_start_codon"]
+            report.has_stop_codon = cds_data["has_stop_codon"]
+            report.stop_codon = cds_data["stop_codon"]
+            report.in_frame = cds_data["in_frame"]
+
+            if not report.has_start_codon:
+                warnings.append("CDS does not begin with ATG.")
+            if not report.has_stop_codon:
+                warnings.append("CDS does not end with a stop codon.")
+            if not report.in_frame:
+                warnings.append("CDS length is not divisible by 3.")
+
+        # Homopolymers — full assembled sequence
+        hp_data = self.analyze_homopolymers(full_seq)
+        report.homopolymer_runs = hp_data["homopolymer_runs"]
+        report.homopolymer_count = hp_data["homopolymer_count"]
+        report.longest_homopolymer = hp_data["longest_homopolymer"]
+
+        # Restriction sites
+        rs_data = self.analyze_restriction_sites(full_seq)
+        report.restriction_hits = rs_data["restriction_hits"]
+        report.restriction_enzymes_present = rs_data["restriction_enzymes_present"]
+
+        # Kozak — try on kozak component, then fall back to full sequence
+        kozak_seq = seq.kozak or full_seq
+        kozak_data = self.analyze_kozak(kozak_seq)
+        report.kozak = kozak_data.get("kozak")
+        if "kozak_warning" in kozak_data:
+            warnings.append(kozak_data["kozak_warning"])
+
+        # Secondary structure
+        if include_structure:
+            struct_data = self.analyze_structure(full_seq)
+            report.structure = struct_data["structure"]
+
+        report.warnings = warnings
+
+        # Cache result
+        seq._analysis_cache[cache_key] = report
+        return report

core/analysis/cai.py

@@ -0,0 +1,187 @@
+"""
+Codon Adaptation Index (CAI) calculation.
+
+Uses BioPython's CodonAdaptationIndex and codon usage tables.
+Supports human and a set of common lab organisms. Additional organisms
+can be added by providing a codon usage table as a dict.
+"""
+from __future__ import annotations
+
+import math
+from typing import Dict, Optional
+
+# Codon usage tables: {codon: relative_adaptiveness}
+# Tables below are RSCU (relative synonymous codon usage) normalized per
+# synonymous family to relative adaptiveness (0–1). Human table derived
+# from Homo sapiens Kazusa database (high-expression genes).
+
+_HUMAN_RSCU: Dict[str, float] = {
+    # Phe
+    "TTT": 0.55, "TTC": 1.00,
+    # Leu
+    "TTA": 0.07, "TTG": 0.19, "CTT": 0.42, "CTC": 0.68, "CTA": 0.16, "CTG": 1.00,
+    # Ile
+    "ATT": 0.71, "ATC": 1.00, "ATA": 0.31,
+    # Met
+    "ATG": 1.00,
+    # Val
+    "GTT": 0.46, "GTC": 0.62, "GTA": 0.27, "GTG": 1.00,
+    # Ser
+    "TCT": 0.85, "TCC": 1.00, "TCA": 0.69, "TCG": 0.27, "AGT": 0.72, "AGC": 0.97,
+    # Pro
+    "CCT": 0.85, "CCC": 1.00, "CCA": 0.83, "CCG": 0.22,
+    # Thr
+    "ACT": 0.74, "ACC": 1.00, "ACA": 0.77, "ACG": 0.27,
+    # Ala
+    "GCT": 0.91, "GCC": 1.00, "GCA": 0.67, "GCG": 0.19,
+    # Tyr
+    "TAT": 0.57, "TAC": 1.00,
+    # Stop
+    "TAA": 1.00, "TAG": 0.22, "TGA": 0.61,
+    # His
+    "CAT": 0.56, "CAC": 1.00,
+    # Gln
+    "CAA": 0.36, "CAG": 1.00,
+    # Asn
+    "AAT": 0.53, "AAC": 1.00,
+    # Lys
+    "AAA": 0.74, "AAG": 1.00,
+    # Asp
+    "GAT": 0.63, "GAC": 1.00,
+    # Glu
+    "GAA": 0.68, "GAG": 1.00,
+    # Cys
+    "TGT": 0.56, "TGC": 1.00,
+    # Trp
+    "TGG": 1.00,
+    # Arg
+    "CGT": 0.17, "CGC": 0.40, "CGA": 0.19, "CGG": 0.48, "AGA": 0.74, "AGG": 1.00,
+    # Gly
+    "GGT": 0.52, "GGC": 1.00, "GGA": 0.67, "GGG": 0.54,
+}
+
+_ECOLI_RSCU: Dict[str, float] = {
+    # Phe
+    "TTT": 1.00, "TTC": 0.59,
+    # Leu
+    "TTA": 0.49, "TTG": 0.74, "CTT": 0.68, "CTC": 0.39, "CTA": 0.24, "CTG": 1.00,
+    # Ile
+    "ATT": 1.00, "ATC": 0.82, "ATA": 0.19,
+    # Met
+    "ATG": 1.00,
+    # Val
+    "GTT": 1.00, "GTC": 0.60, "GTA": 0.73, "GTG": 0.72,
+    # Ser
+    "TCT": 0.92, "TCC": 0.52, "TCA": 0.46, "TCG": 0.46, "AGT": 0.72, "AGC": 1.00,
+    # Pro
+    "CCT": 0.63, "CCC": 0.27, "CCA": 0.67, "CCG": 1.00,
+    # Thr
+    "ACT": 0.95, "ACC": 1.00, "ACA": 0.47, "ACG": 0.81,
+    # Ala
+    "GCT": 0.92, "GCC": 0.70, "GCA": 0.91, "GCG": 1.00,
+    # Tyr
+    "TAT": 1.00, "TAC": 0.67,
+    # Stop
+    "TAA": 1.00, "TAG": 0.10, "TGA": 0.07,
+    # His
+    "CAT": 1.00, "CAC": 0.53,
+    # Gln
+    "CAA": 0.69, "CAG": 1.00,
+    # Asn
+    "AAT": 0.89, "AAC": 1.00,
+    # Lys
+    "AAA": 1.00, "AAG": 0.41,
+    # Asp
+    "GAT": 1.00, "GAC": 0.52,
+    # Glu
+    "GAA": 1.00, "GAG": 0.41,
+    # Cys
+    "TGT": 1.00, "TGC": 0.54,
+    # Trp
+    "TGG": 1.00,
+    # Arg
+    "CGT": 1.00, "CGC": 0.68, "CGA": 0.19, "CGG": 0.18, "AGA": 0.07, "AGG": 0.05,
+    # Gly
+    "GGT": 1.00, "GGC": 0.69, "GGA": 0.35, "GGG": 0.26,
+}
+
+CODON_TABLES: Dict[str, Dict[str, float]] = {
+    "human": _HUMAN_RSCU,
+    "ecoli": _ECOLI_RSCU,
+}
+
+
+def calculate_cai(
+    cds: str,
+    organism: str = "human",
+    custom_table: Optional[Dict[str, float]] = None,
+) -> float:
+    """
+    Calculate the Codon Adaptation Index for a CDS.
+
+    Parameters
+    ----------
+    cds : str
+        Coding sequence (DNA, T not U). Must start with ATG and be
+        divisible by 3. Stop codon is excluded from the CAI calculation.
+    organism : str
+        Key into CODON_TABLES. Ignored if custom_table is provided.
+    custom_table : dict, optional
+        Custom {codon: relative_adaptiveness} table (values 0–1).
+
+    Returns
+    -------
+    float
+        CAI value in [0, 1]. Higher is better adapted.
+    """
+    seq = cds.upper().replace("U", "T")
+    if len(seq) % 3 != 0:
+        raise ValueError("CDS length is not divisible by 3.")
+
+    table = custom_table if custom_table else CODON_TABLES.get(organism)
+    if table is None:
+        raise ValueError(
+            f"Unknown organism '{organism}'. "
+            f"Available: {list(CODON_TABLES.keys())}. "
+            "Provide a custom_table to use another organism."
+        )
+
+    codons = [seq[i:i+3] for i in range(0, len(seq), 3)]
+    # Exclude stop codons from CAI
+    stop_codons = {"TAA", "TAG", "TGA"}
+    codons = [c for c in codons if c not in stop_codons]
+
+    if not codons:
+        return 0.0
+
+    log_sum = 0.0
+    unknown = []
+    for codon in codons:
+        w = table.get(codon)
+        if w is None or w <= 0:
+            unknown.append(codon)
+            continue
+        log_sum += math.log(w)
+
+    if unknown:
+        # Non-standard codons (ambiguity codes, etc.) — skip gracefully
+        n = len(codons) - len(unknown)
+    else:
+        n = len(codons)
+
+    if n == 0:
+        return 0.0
+
+    return math.exp(log_sum / n)
+
+
+def codon_usage_report(cds: str) -> Dict[str, int]:
+    """Return a frequency count of each codon in the CDS."""
+    seq = cds.upper().replace("U", "T")
+    if len(seq) % 3 != 0:
+        raise ValueError("CDS length is not divisible by 3.")
+    freq: Dict[str, int] = {}
+    for i in range(0, len(seq), 3):
+        codon = seq[i:i+3]
+        freq[codon] = freq.get(codon, 0) + 1
+    return freq

core/analysis/dinucleotide.py

@@ -0,0 +1,74 @@
+"""
+Dinucleotide frequency analysis.
+
+CpG dinucleotides are immunostimulatory in mammals (recognized by TLR9).
+UpA dinucleotides are associated with mRNA instability (targeted by
+cellular RNases). Quantifying these helps optimize mRNA therapeutics.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple
+
+
+@dataclass
+class DinucleotideReport:
+    """Dinucleotide frequency analysis results."""
+    frequencies: Dict[str, int]          # all dinucleotide counts
+    normalized: Dict[str, float]         # frequencies / total dinucleotides
+    cpg_count: int = 0
+    upa_count: int = 0
+    cpg_positions: List[int] = field(default_factory=list)
+    upa_positions: List[int] = field(default_factory=list)
+    total_dinucleotides: int = 0
+
+
+def analyze_dinucleotides(
+    sequence: str,
+    flag_cpg: bool = True,
+    flag_upa: bool = True,
+) -> DinucleotideReport:
+    """
+    Analyze dinucleotide frequencies in a nucleotide sequence.
+
+    Parameters
+    ----------
+    sequence : str
+        DNA or RNA sequence.
+    flag_cpg : bool
+        Track CpG positions.
+    flag_upa : bool
+        Track UpA (TpA in DNA) positions.
+
+    Returns
+    -------
+    DinucleotideReport
+    """
+    seq = sequence.upper()
+    n = len(seq)
+
+    frequencies: Dict[str, int] = {}
+    cpg_positions: List[int] = []
+    upa_positions: List[int] = []
+
+    for i in range(n - 1):
+        di = seq[i:i + 2]
+        frequencies[di] = frequencies.get(di, 0) + 1
+
+        if flag_cpg and di == "CG":
+            cpg_positions.append(i)
+        if flag_upa and di in ("TA", "UA"):
+            upa_positions.append(i)
+
+    total = sum(frequencies.values())
+    normalized = {k: v / total if total > 0 else 0.0 for k, v in frequencies.items()}
+
+    return DinucleotideReport(
+        frequencies=frequencies,
+        normalized=normalized,
+        cpg_count=len(cpg_positions),
+        upa_count=len(upa_positions),
+        cpg_positions=cpg_positions,
+        upa_positions=upa_positions,
+        total_dinucleotides=total,
+    )

core/analysis/gc_content.py

@@ -0,0 +1,68 @@
+"""GC content calculation — global and sliding window."""
+from __future__ import annotations
+
+from typing import Optional
+import numpy as np
+
+
+def gc_fraction(sequence: str) -> float:
+    """Return global GC fraction (0.0 – 1.0) for a nucleotide sequence."""
+    seq = sequence.upper()
+    if not seq:
+        return 0.0
+    gc = sum(1 for nt in seq if nt in "GC")
+    return gc / len(seq)
+
+
+def gc_percent(sequence: str) -> float:
+    """Return global GC% (0 – 100)."""
+    return gc_fraction(sequence) * 100.0
+
+
+def gc_sliding_window(
+    sequence: str,
+    window: int = 100,
+    step: int = 1,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Compute GC% in a sliding window across the sequence.
+
+    Returns
+    -------
+    positions : np.ndarray of int
+        Centre position of each window (0-based nucleotide index).
+    gc_values : np.ndarray of float
+        GC% (0–100) for each window.
+    """
+    seq = sequence.upper()
+    n = len(seq)
+    if n == 0 or window > n:
+        return np.array([], dtype=int), np.array([], dtype=float)
+
+    # Pre-compute cumulative GC counts for O(n) sliding window
+    gc_flags = np.array([1 if nt in "GC" else 0 for nt in seq], dtype=np.int32)
+    cumsum = np.zeros(n + 1, dtype=np.int32)
+    cumsum[1:] = np.cumsum(gc_flags)
+
+    starts = np.arange(0, n - window + 1, step)
+    ends = starts + window
+    gc_counts = cumsum[ends] - cumsum[starts]
+    gc_values = gc_counts / window * 100.0
+    positions = starts + window // 2
+
+    return positions, gc_values
+
+
+def gc_by_codon_position(cds: str) -> dict[str, float]:
+    """
+    Return GC% at each codon position (GC1, GC2, GC3).
+    cds must be in-frame and length divisible by 3.
+    """
+    seq = cds.upper()
+    if len(seq) % 3 != 0:
+        raise ValueError("CDS length is not divisible by 3.")
+    codons = [seq[i:i+3] for i in range(0, len(seq), 3)]
+    gc1 = sum(1 for c in codons if c[0] in "GC") / len(codons) * 100
+    gc2 = sum(1 for c in codons if c[1] in "GC") / len(codons) * 100
+    gc3 = sum(1 for c in codons if c[2] in "GC") / len(codons) * 100
+    return {"GC1": gc1, "GC2": gc2, "GC3": gc3, "GC_overall": gc_percent(seq)}

core/analysis/homopolymers.py

@@ -0,0 +1,84 @@
+"""Homopolymer detection in nucleotide sequences."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class HomopolymerRun:
+    nucleotide: str    # the repeated base ("A", "T", "G", "C")
+    start: int         # 0-based start position
+    end: int           # 0-based end position (exclusive)
+    length: int
+
+    def __repr__(self) -> str:
+        return f"HomopolymerRun({self.nucleotide!r} ×{self.length} @ [{self.start}:{self.end}])"
+
+
+def detect_homopolymers(
+    sequence: str,
+    min_run: int = 5,
+    bases: str = "ATGC",
+) -> List[HomopolymerRun]:
+    """
+    Detect homopolymer runs (consecutive identical nucleotides) in a sequence.
+
+    Parameters
+    ----------
+    sequence : str
+        Nucleotide sequence (DNA or RNA).
+    min_run : int
+        Minimum run length to report (default 5).
+    bases : str
+        Which bases to check. Default "ATGC" checks all. Use "A" to detect
+        only poly-A, for example.
+
+    Returns
+    -------
+    List[HomopolymerRun]
+        Sorted by start position.
+    """
+    seq = sequence.upper().replace("U", "T")
+    if not seq:
+        return []
+
+    runs: List[HomopolymerRun] = []
+    i = 0
+    n = len(seq)
+
+    while i < n:
+        base = seq[i]
+        if base not in bases:
+            i += 1
+            continue
+        j = i
+        while j < n and seq[j] == base:
+            j += 1
+        run_len = j - i
+        if run_len >= min_run:
+            runs.append(HomopolymerRun(
+                nucleotide=base,
+                start=i,
+                end=j,
+                length=run_len,
+            ))
+        i = j
+
+    return runs
+
+
+def homopolymer_summary(runs: List[HomopolymerRun]) -> dict:
+    """Summarise a list of HomopolymerRun objects."""
+    if not runs:
+        return {"count": 0, "max_length": 0, "longest": None}
+    longest = max(runs, key=lambda r: r.length)
+    by_base = {}
+    for r in runs:
+        by_base.setdefault(r.nucleotide, []).append(r)
+    return {
+        "count": len(runs),
+        "max_length": longest.length,
+        "longest": longest,
+        "by_base": {b: len(v) for b, v in by_base.items()},
+    }

core/analysis/kozak.py

@@ -0,0 +1,138 @@
+"""
+Kozak sequence analysis.
+
+The Kozak consensus for vertebrates is: (GCC)GCCRCCATGG
+Where R = A or G at position -3 relative to ATG.
+
+Scoring follows Cavener & Ray (1991) positional weight matrix approach.
+Positions scored: -6 to +4 relative to the A of ATG (+1 = A, +2 = T, +3 = G).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+
+# Kozak context: positions -6 to +4 (11 nt total, ATG at [6,7,8])
+# Positional frequency matrix derived from vertebrate Kozak sequences.
+# Rows: A, C, G, T. Columns: positions -6 through +4.
+# Normalised to [0, 1] (1 = dominant base at that position).
+_PFM: List[Tuple[float, float, float, float]] = [
+    # pos: -6    -5    -4    -3    -2    -1   +1(A) +2(T) +3(G) +4
+    (0.22, 0.28, 0.28, 0.46, 0.22, 0.22, 1.00, 0.00, 0.00, 0.25),  # A
+    (0.28, 0.28, 0.18, 0.12, 0.22, 0.22, 0.00, 0.00, 0.00, 0.25),  # C
+    (0.22, 0.22, 0.28, 0.30, 0.22, 0.22, 0.00, 0.00, 1.00, 0.25),  # G
+    (0.28, 0.22, 0.26, 0.12, 0.34, 0.34, 0.00, 1.00, 0.00, 0.25),  # T
+]
+_BASES = "ACGT"
+_CONTEXT_LEN = 10  # positions -6 through +4 (10 positions around ATG start)
+
+
+@dataclass
+class KozakResult:
+    """Result of Kozak consensus analysis for one ATG."""
+    atg_position: int         # 0-based position of A in ATG within the full sequence
+    context: str              # extracted Kozak context window
+    score: float              # normalised score 0–1 (1 = perfect consensus)
+    has_optimal_r3: bool      # A or G at position -3
+    matches_consensus: bool   # True if score > 0.7 threshold
+    strength: str             # "strong", "adequate", "weak"
+
+    def __repr__(self) -> str:
+        return (
+            f"KozakResult(pos={self.atg_position}, "
+            f"context={self.context!r}, score={self.score:.2f}, "
+            f"strength={self.strength!r})"
+        )
+
+
+def _score_context(context: str) -> float:
+    """Score a 10-nt Kozak context window against the PFM."""
+    if len(context) != 10:
+        return 0.0
+    total = 0.0
+    for i, nt in enumerate(context.upper()):
+        if nt not in _BASES:
+            continue
+        row = _BASES.index(nt)
+        total += _PFM[row][i]
+    # Max possible score: 10 (1.0 per position)
+    return total / 10.0
+
+
+def _strength(score: float) -> str:
+    # Thresholds calibrated against achievable scores with the PFM above.
+    # Max achievable for ideal Kozak (GCCACCATGG) ≈ 0.48.
+    if score >= 0.43:
+        return "strong"
+    if score >= 0.33:
+        return "adequate"
+    return "weak"
+
+
+def check_kozak(sequence: str, atg_position: Optional[int] = None) -> KozakResult:
+    """
+    Analyse the Kozak context around the first (or specified) ATG in the sequence.
+
+    Parameters
+    ----------
+    sequence : str
+        Nucleotide sequence (DNA).
+    atg_position : int, optional
+        0-based position of the ATG to analyse. If None, uses the first ATG found.
+
+    Returns
+    -------
+    KozakResult
+    """
+    seq = sequence.upper().replace("U", "T")
+
+    if atg_position is None:
+        pos = seq.find("ATG")
+        if pos == -1:
+            raise ValueError("No ATG start codon found in sequence.")
+    else:
+        pos = atg_position
+        if seq[pos:pos+3] != "ATG":
+            raise ValueError(f"No ATG at position {pos}.")
+
+    # Extract context: 6 nt before ATG + ATG + 1 nt after = 10 nt total
+    ctx_start = pos - 6
+    ctx_end = pos + 4   # positions -6 to +4 (ATG at indices 6,7,8 of the 10-nt window)
+    # Pad with N if near sequence edges
+    left_pad = max(0, -ctx_start) * "N"
+    right_pad = max(0, ctx_end - len(seq)) * "N"
+    actual_start = max(0, ctx_start)
+    actual_end = min(len(seq), ctx_end)
+    context = left_pad + seq[actual_start:actual_end] + right_pad
+
+    score = _score_context(context)
+
+    # -3 position relative to ATG = index 3 in the 10-nt context
+    r3_base = context[3] if len(context) > 3 else "N"
+    has_r3 = r3_base in "AG"
+
+    return KozakResult(
+        atg_position=pos,
+        context=context,
+        score=score,
+        has_optimal_r3=has_r3,
+        matches_consensus=score >= 0.55,
+        strength=_strength(score),
+    )
+
+
+def find_all_kozak_contexts(sequence: str, min_score: float = 0.0) -> List[KozakResult]:
+    """Find and score Kozak contexts for every ATG in the sequence."""
+    seq = sequence.upper().replace("U", "T")
+    results = []
+    start = 0
+    while True:
+        pos = seq.find("ATG", start)
+        if pos == -1:
+            break
+        result = check_kozak(seq, pos)
+        if result.score >= min_score:
+            results.append(result)
+        start = pos + 1
+    return results

core/analysis/restriction_sites.py

@@ -0,0 +1,174 @@
+"""
+Restriction enzyme site scanning.
+
+Uses BioPython's Restriction module for recognition site data.
+Falls back to a small curated built-in table for the most common
+cloning enzymes if BioPython is unavailable.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+# Built-in recognition patterns for common enzymes (IUPAC notation)
+# Used as fallback and for quick lookups without full Bio.Restriction import.
+COMMON_ENZYMES: Dict[str, str] = {
+    # Type IIS / Golden Gate
+    "BsaI":   "GGTCTC",
+    "BbsI":   "GAAGAC",
+    "Esp3I":  "CGTCTC",
+    "SapI":   "GCTCTTC",
+    "BsmBI":  "CGTCTC",
+    # Classic cloning
+    "EcoRI":  "GAATTC",
+    "HindIII":"AAGCTT",
+    "BamHI":  "GGATCC",
+    "NcoI":   "CCATGG",
+    "NheI":   "GCTAGC",
+    "XhoI":   "CTCGAG",
+    "XbaI":   "TCTAGA",
+    "SpeI":   "ACTAGT",
+    "NotI":   "GCGGCCGC",
+    "SalI":   "GTCGAC",
+    "PstI":   "CTGCAG",
+    "KpnI":   "GGTACC",
+    "SmaI":   "CCCGGG",
+    "SacI":   "GAGCTC",
+    "ClaI":   "ATCGAT",
+    # Blunt cutters
+    "EcoRV":  "GATATC",
+    "HpaI":   "GTTAAC",
+    "StuI":   "AGGCCT",
+    "ScaI":   "AGTACT",
+    # Methylation-sensitive
+    "DpnI":   "GATC",
+    "MboI":   "GATC",
+    "Sau3AI": "GATC",
+    # Rare cutters (8+ bp)
+    "SfiI":   "GGCCNNNNNGGCC",
+    "PacI":   "TTAATTAA",
+    "AscI":   "GGCGCGCC",
+    "FseI":   "GGCCGGCC",
+    "SwaI":   "ATTTAAAT",
+    "PmeI":   "GTTTAAAC",
+}
+
+# IUPAC ambiguity → regex character class
+_IUPAC_TO_REGEX: Dict[str, str] = {
+    "A": "A", "T": "T", "G": "G", "C": "C",
+    "R": "[AG]", "Y": "[CT]", "S": "[GC]", "W": "[AT]",
+    "K": "[GT]", "M": "[AC]", "B": "[CGT]", "D": "[AGT]",
+    "H": "[ACT]", "V": "[ACG]", "N": "[ACGT]",
+}
+
+
+def _iupac_to_regex(pattern: str) -> str:
+    import re
+    return "".join(_IUPAC_TO_REGEX.get(c, c) for c in pattern.upper())
+
+
+@dataclass
+class RestrictionSiteHit:
+    enzyme: str
+    recognition_sequence: str
+    position: int     # 0-based start of recognition sequence on forward strand
+    strand: str       # "+" forward, "-" reverse complement
+
+    def __repr__(self) -> str:
+        return (
+            f"RestrictionSiteHit({self.enzyme!r} @ pos {self.position} "
+            f"strand={self.strand!r})"
+        )
+
+
+def _reverse_complement(seq: str) -> str:
+    comp = str.maketrans("ATGCRYSWKMBDHVN", "TACGYRSWMKVHDBN")
+    return seq.upper().translate(comp)[::-1]
+
+
+def scan_restriction_sites(
+    sequence: str,
+    enzymes: Optional[List[str]] = None,
+) -> Dict[str, List[RestrictionSiteHit]]:
+    """
+    Scan a DNA sequence for restriction enzyme recognition sites.
+
+    Parameters
+    ----------
+    sequence : str
+        DNA sequence to scan.
+    enzymes : list of str, optional
+        Enzyme names to check. Defaults to COMMON_ENZYMES.
+
+    Returns
+    -------
+    dict
+        {enzyme_name: [RestrictionSiteHit, ...]}
+        Only enzymes with at least one hit are included.
+    """
+    import re
+
+    seq = sequence.upper().replace("U", "T")
+    rc_seq = _reverse_complement(seq)
+    n = len(seq)
+
+    enzyme_list = enzymes if enzymes else list(COMMON_ENZYMES.keys())
+    results: Dict[str, List[RestrictionSiteHit]] = {}
+
+    for enzyme in enzyme_list:
+        recognition = COMMON_ENZYMES.get(enzyme)
+        if not recognition:
+            # Try BioPython if available
+            try:
+                from Bio.Restriction import AllEnzymes
+                enz_obj = AllEnzymes.get(enzyme)
+                if enz_obj:
+                    recognition = str(enz_obj.site)
+                else:
+                    continue
+            except ImportError:
+                continue
+
+        regex = _iupac_to_regex(recognition)
+        hits: List[RestrictionSiteHit] = []
+
+        # Forward strand
+        for m in re.finditer(f"(?={regex})", seq):
+            hits.append(RestrictionSiteHit(
+                enzyme=enzyme,
+                recognition_sequence=recognition,
+                position=m.start(),
+                strand="+",
+            ))
+
+        # Reverse complement strand (report position on forward)
+        rev_rec = _iupac_to_regex(_reverse_complement(recognition))
+        for m in re.finditer(f"(?={rev_rec})", seq):
+            hits.append(RestrictionSiteHit(
+                enzyme=enzyme,
+                recognition_sequence=recognition,
+                position=m.start(),
+                strand="-",
+            ))
+
+        if hits:
+            results[enzyme] = sorted(hits, key=lambda h: h.position)
+
+    return results
+
+
+def sites_present(
+    sequence: str,
+    enzymes: Optional[List[str]] = None,
+) -> List[str]:
+    """Return list of enzyme names that have at least one hit in the sequence."""
+    return list(scan_restriction_sites(sequence, enzymes).keys())
+
+
+def sites_absent(
+    sequence: str,
+    required_absent: List[str],
+) -> List[str]:
+    """Return list of enzymes from required_absent that ARE present (i.e. violations)."""
+    present = set(sites_present(sequence, required_absent))
+    return [e for e in required_absent if e in present]

core/analysis/structure.py

@@ -0,0 +1,83 @@
+"""
+RNA secondary structure prediction via ViennaRNA.
+
+ViennaRNA (RNA package) must be installed:
+  conda install -c bioconda viennarna
+  or: pip install ViennaRNA (if wheel available for the platform)
+
+Falls back to a stub when ViennaRNA is not available so the rest of the
+app can run without it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+_VIENNARNA_AVAILABLE = False
+try:
+    import RNA  # type: ignore[import-untyped]
+    _VIENNARNA_AVAILABLE = True
+except ImportError:
+    pass
+
+
+@dataclass
+class StructureResult:
+    sequence: str
+    structure: str          # dot-bracket notation
+    mfe: float              # minimum free energy (kcal/mol)
+    ensemble_free_energy: Optional[float] = None
+    centroid_structure: Optional[str] = None
+    centroid_distance: Optional[float] = None
+
+    @property
+    def is_stub(self) -> bool:
+        return self.structure == "" and self.mfe == 0.0
+
+    def __repr__(self) -> str:
+        return (
+            f"StructureResult(mfe={self.mfe:.2f} kcal/mol, "
+            f"len={len(self.sequence)})"
+        )
+
+
+def predict_structure(sequence: str) -> StructureResult:
+    """
+    Predict the MFE secondary structure of an RNA/DNA sequence.
+
+    The sequence is automatically converted from DNA to RNA (T→U) before
+    passing to ViennaRNA, which expects RNA input.
+
+    Returns a StructureResult. If ViennaRNA is not installed, returns a
+    stub result with empty structure and mfe=0.0.
+    """
+    rna_seq = sequence.upper().replace("T", "U")
+
+    if not _VIENNARNA_AVAILABLE:
+        return StructureResult(
+            sequence=rna_seq,
+            structure="",
+            mfe=0.0,
+        )
+
+    # MFE structure
+    structure, mfe = RNA.fold(rna_seq)  # type: ignore[attr-defined]
+
+    # Ensemble / centroid (for longer seqs this is informative)
+    md = RNA.md()  # type: ignore[attr-defined]
+    fc = RNA.fold_compound(rna_seq, md)  # type: ignore[attr-defined]
+    _, ensemble_free_energy = fc.pf()
+    centroid_structure, centroid_distance = fc.centroid()
+
+    return StructureResult(
+        sequence=rna_seq,
+        structure=structure,
+        mfe=mfe,
+        ensemble_free_energy=ensemble_free_energy,
+        centroid_structure=centroid_structure,
+        centroid_distance=centroid_distance,
+    )
+
+
+def is_viennarna_available() -> bool:
+    return _VIENNARNA_AVAILABLE

core/analysis/uridine.py

@@ -0,0 +1,81 @@
+"""
+Uridine content analysis for mRNA sequences.
+
+High uridine content can trigger innate immune responses. Modified
+nucleotides (N1-methylpseudouridine) mitigate this, but it's still
+useful to quantify uridine distribution.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Tuple
+
+
+@dataclass
+class UridineReport:
+    """Uridine content analysis results."""
+    total_u: int
+    total_length: int
+    u_fraction: float          # 0.0 – 1.0
+    u_percent: float           # 0 – 100
+    ua_ratio: float            # U/A ratio
+    high_u_stretches: List[Tuple[int, int, int]]  # (start, end, length) of high-U regions
+
+
+def analyze_uridine(
+    sequence: str,
+    window: int = 50,
+    threshold: float = 0.40,
+) -> UridineReport:
+    """
+    Analyze uridine content in an RNA/DNA sequence.
+
+    Parameters
+    ----------
+    sequence : str
+        Nucleotide sequence (DNA or RNA).
+    window : int
+        Sliding window size for high-U stretch detection.
+    threshold : float
+        U fraction threshold for flagging high-U windows.
+
+    Returns
+    -------
+    UridineReport
+    """
+    seq = sequence.upper().replace("T", "U")
+    n = len(seq)
+
+    total_u = seq.count("U")
+    total_a = seq.count("A")
+
+    u_fraction = total_u / n if n > 0 else 0.0
+    ua_ratio = total_u / total_a if total_a > 0 else float("inf")
+
+    # Find high-U stretches using sliding window
+    stretches: List[Tuple[int, int, int]] = []
+    if n >= window:
+        in_stretch = False
+        stretch_start = 0
+        for i in range(n - window + 1):
+            win = seq[i:i + window]
+            u_frac = win.count("U") / window
+            if u_frac >= threshold:
+                if not in_stretch:
+                    stretch_start = i
+                    in_stretch = True
+            else:
+                if in_stretch:
+                    stretches.append((stretch_start, i + window - 1, i + window - 1 - stretch_start))
+                    in_stretch = False
+        if in_stretch:
+            stretches.append((stretch_start, n, n - stretch_start))
+
+    return UridineReport(
+        total_u=total_u,
+        total_length=n,
+        u_fraction=u_fraction,
+        u_percent=u_fraction * 100,
+        ua_ratio=ua_ratio,
+        high_u_stretches=stretches,
+    )

core/data/__init__.py

@@ -0,0 +1 @@
+"""Seed data for the application."""

core/data/seed_backbones.py

@@ -0,0 +1,80 @@
+"""
+Seed plasmid backbones for the assembly workflow.
+
+Provides demo backbone data for common expression vectors.
+Sequences are truncated/representative for demo purposes.
+"""
+from __future__ import annotations
+
+from typing import List
+
+from core.models.plasmid import PlasmidBackbone, PlasmidFeature
+
+
+def get_seed_backbones() -> List[PlasmidBackbone]:
+    """Return demo plasmid backbones."""
+    backbones = []
+
+    # pUC19 — classic high-copy cloning vector
+    backbones.append(PlasmidBackbone(
+        name="pUC19",
+        description="High-copy number E. coli cloning vector (2,686 bp). Contains lacZ-alpha MCS, ampicillin resistance, and pMB1 origin.",
+        sequence="TCGCGCGTTTCGGTGATGACGGTGAAAACCTCTGACACATGCAGCTCCCGGAGACGGTCACAGCTTGTCTGTAAGCGGATGCCGGGAGCAGACAAGCCCGTCAGGGCGCGTCAGCGGGTGTTGGCGGGTGTCGGGGCTGGCTTAACTATGCGGCATCAGAGCAGATTGTACTGAGAGTGCACCATATGCGGTGTGAAATACCGCACAGATGCGTAAGGAGAAAATACCGCATCAGGCGCCATTCGCCATTCAGGCTGCGCAACTGTTGGGAAGGGCGATCGGTGCGGGCCTCTTCGCTATTACGCCAGCTGGCGAAAGGGGGATGTGCTGCAAGGCGATTAAGTTGGGTAACGCCAGGGTTTTCCCAGTCACGACGTTGTAAAACGACGGCCAGTGAATTCGAGCTCGGTACCCGGGGATCCTCTAGAGTCGACCTGCAGGCATGCAAGCTTGGCGTAATCATGGTCATAGCTGTTTCCTGTGTGAAATTGTTATCCGCTCACAATTCCACACAACATACGAGCCGGAAGCATAAAGTGTAAAGCCTGGGGTGCCTAATGAGTGAGCTAACTCACATTAATTGCGTTGCGCTCACTGCCCGCTTTCCAGTCGGGAAACCTGTCGTGCCAGCTGCATTAATGAATCGGCCAACGCGCGGGGAGAGGCGGTTTGCGTATTGGGCGCTCTTCCGCTTCCTCGCTCACTGACTCGCTGCGCTCGGTCGTTCGGCTGCGGCGAGCGGTATCAGCTCACTCAAAGGCGGTAATACGGTTATCCACAGAATCAGGGGATAACGCAGGAAAGAACATGTGAGCAAAAGGCCAGCAAAAGGCCAGGAACCGTAAAAAGGCCGCGTTGCTGGCGTTTTTCCATAGGCTCCGCCCCCCTGACGAGCATCACAAAAATCGACGCTCAAGTCAGAGGTGGCGAAACCCGACAGGACTATAAAGATACCAGGCGTTTCCCCCTGGAAGCTCCCTCGTGCGCTCTCCTGTTCCGACCCTGCCGCTTACCGGATACCTGTCCGCCTTTCTCCCTTCGGGAAGCGTGGCGCTTTCTCATAGCTCACGCTGTAGGTATCTCAGTTCGGTGTAGGTCGTTCGCTCCAAGCTGGGCTGTGTGCACGAACCCCCCGTTCAGCCCGACCGCTGCGCCTTATCCGGTAACTATCGTCTTGAGTCCAACCCGGTAAGACACGACTTATCGCCACTGGCAGCAGCCACTGGTAACAGGATTAGCAGAGCGAGGTATGTAGGCGGTGCTACAGAGTTCTTGAAGTGGTGGCCTAACTACGGCTACACTAGAAGAACAGTATTTGGTATCTGCGCTCTGCTGAAGCCAGTTACCTTCGGAAAAAGAGTTGGTAGCTCTTGATCCGGCAAACAAACCACCGCTGGTAGCGGTGGTTTTTTTGTTTGCAAGCAGCAGATTACGCGCAGAAAAAAAGGATCTCAAGAAGATCCTTTGATCTTTTCTACGGGGTCTGACGCTCAGTGGAACGAAAACTCACGTTAAGGGATTTTGGTCATGAGATTATCAAAAAGGATCTTCACCTAGATCCTTTTAAATTAAAAATGAAGTTTTAAATCAATCTAAAGTATATATGAGTAAACTTGGTCTGACAGTTACCAATGCTTAATCAGTGAGGCACCTATCTCAGCGATCTGTCTATTTCGTTCATCCATAGTTGCCTGACTCCCCGTCGTGTAGATAACTACGATACGGGAGGGCTTACCATCTGGCCCCAGTGCTGCAATGATACCGCGAGACCCACGCTCACCGGCTCCAGATTTATCAGCAATAAACCAGCCAGCCGGAAGGGCCGAGCGCAGAAGTGGTCCTGCAACTTTATCCGCCTCCATCCAGTCTATTAATTGTTGCCGGGAAGCTAGAGTAAGTAGTTCGCCAGTTAATAGTTTGCGCAACGTTGTTGCCATTGCTACAGGCATCGTGGTGTCACGCTCGTCGTTTGGTATGGCTTCATTCAGCTCCGGTTCCCAACGATCAAGGCGAGTTACATGATCCCCCATGTTGTGCAAAAAAGCGGTTAGCTCCTTCGGTCCTCCGATCGTTGTCAGAAGTAAGTTGGCCGCAGTGTTATCACTCATGGTTATGGCAGCACTGCATAATTCTCTTACTGTCATGCCATCCGTAAGATGCTTTTCTGTGACTGGTGAGTACTCAACCAAGTCATTCTGAGAATAGTGTATGCGGCGACCGAGTTGCTCTTGCCCGGCGTCAATACGGGATAATACCGCGCCACATAGCAGAACTTTAAAAGTGCTCATCATTGGAAAACGTTCTTCGGGGCGAAAACTCTCAAGGATCTTACCGCTGTTGAGATCCAGTTCGATGTAACCCACTCGTGCACCCAACTGATCTTCAGCATCTTTTACTTTCACCAGCGTTTCTGGGTGAGCAAAAACAGGAAGGCAAAATGCCGCAAAAAAGGGAATAAGGGCGACACGGAAATGTTGAATACTCATACTCTTCCTTTTTCAATATTATTGAAGCATTTATCAGGGTTATTGTCTCATGAGCGGATACATATTTGAATGTATTTAGAAAAATAAACAAATAGGGGTTCCGCGCACATTTCCCCGAAAAGTGCCACCTGACGTC",
+        features=[
+            PlasmidFeature(label="AmpR", feature_type="resistance", start=1629, end=2489, strand="-", color="#EF4444"),
+            PlasmidFeature(label="pMB1 ori", feature_type="ori", start=2489, end=2686, color="#3B82F6"),
+            PlasmidFeature(label="lacZ-alpha", feature_type="other", start=217, end=580, color="#10B981"),
+            PlasmidFeature(label="MCS", feature_type="cloning_site", start=396, end=452, color="#F59E0B"),
+        ],
+        cloning_sites=["EcoRI", "SacI", "KpnI", "BamHI", "XbaI", "SalI", "PstI", "SphI", "HindIII"],
+        source="library",
+    ))
+
+    # pcDNA3.1 — mammalian expression vector
+    backbones.append(PlasmidBackbone(
+        name="pcDNA3.1(+)",
+        description="Mammalian expression vector (5,428 bp). CMV promoter, BGH polyA, neomycin/G418 resistance, SV40 ori.",
+        sequence="GACGGATCGGGAGATCTCCCGATCCCCTATGGTGCACTCTCAGTACAATCTGCTCTGATGCCGCATAGTTAAGCCAGTATCTGCTCCCTGCTTGTGTGTTGGAGGTCGCTGAGTAGTGCGCGAGCAAAATTTAAGCTACAACAAGGCAAGGCTTGACCGACAATTGCATGAAGAATCTGCTTAGGGTTAGGCGTTTTGCGCTGCTTCGCGATGTACGGGCCAGATATACGCGTTGACATTGATTATTGACTAGTTATTAATAGTAATCAATTACGGGGTCATTAGTTCATAGCCCATATATGGAGTTCCGCGTTACATAACTTACGGTAAATGGCCCGCCTGGCTGACCGCCCAACGACCCCCGCCCATTGACGTCAATAATGACGTATGTTCCCATAGTAACGCCAATAGGGACTTTCCATTGACGTCAATGGGTGGAGTATTTACGGTAAACTGCCCACTTGGCAGTACATCAAGTGTATCATATGCCAAGTACGCCCCCTATTGACGTCAATGACGGTAAATGGCCCGCCTGGCATTATGCCCAGTACATGACCTTATGGGACTTTCCTACTTGGCAGTACATCTACGTATTAGTCATCGCTATTACCATGGTGATGCGGTTTTGGCAGTACATCAATGGGCGTGGATAGCGGTTTGACTCACGGGGATTTCCAAGTCTCCACCCCATTGACGTCAATGGGAGTTTGTTTTGGCACCAAAATCAACGGGACTTTCCAAAATGTCGTAACAACTCCGCCCCATTGACGCAAATGGGCGGTAGGCGTGTACGGTGGGAGGTCTATATAAGCAGAGCTGGTTTAGTGAACCGTCAGATC" + "A" * 200,
+        features=[
+            PlasmidFeature(label="CMV promoter", feature_type="promoter", start=1, end=590, color="#8B5CF6"),
+            PlasmidFeature(label="MCS", feature_type="cloning_site", start=895, end=1010, color="#F59E0B"),
+            PlasmidFeature(label="BGH polyA", feature_type="terminator", start=1010, end=1234, color="#EF4444"),
+            PlasmidFeature(label="NeoR/KanR", feature_type="resistance", start=1850, end=2644, strand="+", color="#10B981"),
+            PlasmidFeature(label="SV40 ori", feature_type="ori", start=1234, end=1450, color="#3B82F6"),
+        ],
+        cloning_sites=["NheI", "BamHI", "EcoRI", "EcoRV", "BstXI", "NotI", "XhoI", "XbaI", "ApaI", "HindIII", "KpnI"],
+        source="library",
+    ))
+
+    # pET-28a — bacterial expression with His-tag
+    backbones.append(PlasmidBackbone(
+        name="pET-28a(+)",
+        description="E. coli T7 expression vector (5,369 bp). N-terminal His-tag, T7 promoter, kanamycin resistance.",
+        sequence="ATCCGGATATAGTTCCTCCTTTCAGCAAAAAACCCCTCAAGACCCGTTTAGAGGCCCCAAGGGGTTATGCTAGTTATTGCTCAGCGGTGGCAGCAGCCAACTCAGCTTCCTTTCGGGCTTTGTTAGCAGCCGGATCTCAGTGGTGGTGGTGGTGGTGCTCGAGTGCGGCCGCAAGCTTGTCGACGGAGCTCGAATTCGGATCCGATATCGAATTCCTGCAGCCCGGGGGATCCACTAGTTCTAGAGCGGCCGCCACCGCGGTGGAGCTCCAGCTTTTGTTCCCTTTAGTGAGGGTTAATTGCGCGCTTGGCGTAATCATGGTCATAGCTGTTTCCTGTGTGAAATTGTTATCCGCTCACAATTCCACACAACATACGAGCCGGAAGCATAAAGTGTAAAGCCTGGGGTGCCTAATGAGTGAGCTAACTCACATTAATTGCGTTGCGCTCACTGCCCGCTTTCCAGTCGGGAAACCTGTCGTGCCAGCTGCATTAATGAATCGGCCAACGCGCGGGGAGAGGCGGTTTGCGTATTGGGCGCTCTTCCGCTTCCTCGCTCACTGACTCGCTGCGCTCGGTCGTTCGGCTGCGGCGAGCGGTATCAGCTCACTCAAAGGCGGTAATACGGTTATCCACAGAATCAGGGGATAACGCAGGAAAGAACATGTGAGCAAAAGGCCAGCAAAAGGCCAGGAACCGTAAAAAGGCCGCGTTGCTGGCG" + "T" * 100,
+        features=[
+            PlasmidFeature(label="T7 promoter", feature_type="promoter", start=1, end=50, color="#8B5CF6"),
+            PlasmidFeature(label="His-tag", feature_type="tag", start=50, end=80, color="#F59E0B"),
+            PlasmidFeature(label="MCS", feature_type="cloning_site", start=80, end=200, color="#F59E0B"),
+            PlasmidFeature(label="KanR", feature_type="resistance", start=500, end=1300, color="#10B981"),
+            PlasmidFeature(label="pBR322 ori", feature_type="ori", start=1300, end=1800, color="#3B82F6"),
+        ],
+        cloning_sites=["NcoI", "NdeI", "BamHI", "EcoRI", "SalI", "HindIII", "NotI", "XhoI", "NheI"],
+        source="library",
+    ))
+
+    # pGEM-T — TA cloning vector
+    backbones.append(PlasmidBackbone(
+        name="pGEM-T Easy",
+        description="TA cloning vector (3,015 bp). T7 and SP6 promoters flanking MCS within lacZ, ampicillin resistance.",
+        sequence="GGGCGAATTGGGCCCGACGTCGCATGCTCCCGGCCGCCATGGCGGCCGCGGGAATTCGATTTAAATCTAGAGTCGACCTGCAGGCATGCAAGCTTGAGTATTCTATAGTGTCACCTAAATAGCTTGGCGTAATCATGGTCATAGCTGTTTCCTGTGTGAAATTGTTATCCGCTCACAATTCCACACAACATACGAGCCGGAAGCATAAAGTGTAAAGCCTGGGGTGCCTAATGAGTGAGCTAACTCACATTAATTGCGTTGCGCTCACTGCCCGCTTTCCAGTCGGGAAACCTGTCGTGCCAGCTGCATTAATGAATCGGCCAACGCGCGGGGAGAGGCGGTTTGCGTATTGGGCGCTCTTCCGCTTCCTCGCTCACTGACTCGCTGCGCTCGGTCGTTCGGCTGCGGCGAGCGGTATCAGCTCACTCAAAGGCGGTAATACGGTTATCCACAGAATCAGGGGATAACGCAGGAAAGAACAT" + "A" * 100,
+        features=[
+            PlasmidFeature(label="T7 promoter", feature_type="promoter", start=1, end=30, color="#8B5CF6"),
+            PlasmidFeature(label="SP6 promoter", feature_type="promoter", start=180, end=210, strand="-", color="#8B5CF6"),
+            PlasmidFeature(label="MCS", feature_type="cloning_site", start=30, end=180, color="#F59E0B"),
+            PlasmidFeature(label="AmpR", feature_type="resistance", start=350, end=1200, color="#EF4444"),
+        ],
+        cloning_sites=["EcoRI", "SacI", "BstXI", "NotI", "SalI", "NcoI", "BamHI", "SpeI", "ApaI"],
+        source="library",
+    ))
+
+    return backbones

core/data/seed_parts.py

@@ -0,0 +1,197 @@
+"""
+Seed parts library with common, well-characterized sequence components.
+
+These are loaded on app startup to provide a starting library for users.
+"""
+from typing import List
+
+from core.models.parts import UTR5Part, KozakPart, CDSPart, UTR3Part, PolyAPart, SequencePart
+
+
+def get_seed_parts() -> List[SequencePart]:
+    """Return a list of seed parts to populate the library."""
+
+    parts = []
+
+    # ── 5' UTRs ────────────────────────────────────────────────────────────────
+
+    # Strong constitutive 5'UTR from β-globin
+    parts.append(UTR5Part(
+        name="β-globin_5UTR",
+        sequence="GTTGCTCCTTCGGGCTGCTGGGGTGAATAGTTCTGCCTTCGCGGCGCCGCCAAGTCCT",
+        source="library",
+    ))
+
+    # CMV 5'UTR - very strong for mammalian expression
+    parts.append(UTR5Part(
+        name="CMV_5UTR",
+        sequence="GACATTGATTATTGACTAGTTATTAATAGTAATCAATTACGGGGTCATTAGTTCATAGCCCATATATGGAGTTCCGCGTTACATAACTTACGGTAAATGGCCCGCCTGGCTGACCGCCCAACGACCCCCGCCCATTGACGTCAATAATGACGTATGTTCCCATAGTAACGCCAATAGGGACTTTCCATTGACGTC",
+        source="library",
+    ))
+
+    # HBB 5'UTR - hemoglobin beta
+    parts.append(UTR5Part(
+        name="HBB_5UTR",
+        sequence="ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCAT",
+        source="library",
+    ))
+
+    # GAPDH 5'UTR - housekeeping gene
+    parts.append(UTR5Part(
+        name="GAPDH_5UTR",
+        sequence="CGCTCTCTGCTCCTCCTGTTCGACAGTCAGCCGCATCTTCTTTTGCGTCGCCAGCCGAGCCACATCGCTC",
+        source="library",
+    ))
+
+    # Minimal synthetic 5'UTR - very short, minimal structure
+    parts.append(UTR5Part(
+        name="Minimal_5UTR",
+        sequence="GGGAAATAAGAGAGAAAAGAAGAGTAAGAAGAAATATAAGAGCCACC",
+        source="library",
+    ))
+
+    # ── Kozak sequences ───────────────────────────────────────────────────────
+
+    # Optimal Kozak consensus
+    parts.append(KozakPart(
+        name="Kozak_Optimal",
+        sequence="GCCACCATG",
+        source="library",
+        consensus_score=1.0,
+        matches_canonical=True,
+    ))
+
+    # Strong Kozak variant
+    parts.append(KozakPart(
+        name="Kozak_Strong",
+        sequence="GCCGCCATG",
+        source="library",
+        consensus_score=0.95,
+        matches_canonical=True,
+    ))
+
+    # Moderate Kozak
+    parts.append(KozakPart(
+        name="Kozak_Moderate",
+        sequence="ACCATG",
+        source="library",
+        consensus_score=0.7,
+        matches_canonical=False,
+    ))
+
+    # ── CDS ───────────────────────────────────────────────────────────────────
+
+    # EGFP - Enhanced Green Fluorescent Protein (codon optimized)
+    parts.append(CDSPart(
+        name="EGFP_CDS",
+        sequence="ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA",
+        source="library",
+        has_start_codon=True,
+        has_stop_codon=True,
+    ))
+
+    # Luciferase - reporter gene
+    parts.append(CDSPart(
+        name="Luciferase_CDS",
+        sequence="ATGGAAGACGCCAAAAACATAAAGAAAGGCCCGGCGCCATTCTATCCGCTGGAAGATGGAACCGCTGGAGAGCAACTGCATAAGGCTATGAAGAGATACGCCCTGGTTCCTGGAACAATTGCTTTTACAGATGCACATATCGAGGTGGACATCACTTACGCTGAGTACTTCGAAATGTCCGTTCGGTTGGCAGAAGCTATGAAACGATATGGGCTGAATACAAATCACAGAATCGTCGTATGCAGTGAAAACTCTCTTCAATTCTTTATGCCGGTGTTGGGCGCGTTATTTATCGGAGTTGCAGTTGCGCCCGCGAACGACATTTATAATGAACGTGAATTGCTCAACAGTATGGGCATTTCGCAGCCTACCGTGGTGTTCGTTTCCAAAAAGGGGTTGCAAAAAATTTTGAACGTGCAAAAAAAGCTCCCAATCATCCAAAAAATTATTATCATGGATTCTAAAACGGATTACCAGGGATTTCAGTCGATGTACACGTTCGTCACATCTCATCTACCTCCCGGTTTTAATGAATACGATTTTGTGCCAGAGTCCTTCGATAGGGACAAGACAATTGCACTGATCATGAACTCCTCTGGATCTACTGGTCTGCCTAAAGGTGTCGCTCTGCCTCATAGAACTGCCTGCGTGAGATTCTCGCATGCCAGAGATCCTATTTTTGGCAATCAAATCATTCCGGATACTGCGATTTTAAGTGTTGTTCCATTCCATCACGGTTTTGGAATGTTTACTACACTCGGATATTTGATATGTGGATTTCGAGTCGTCTTAATGTATAGATTTGAAGAAGAGCTGTTTCTGAGGAGCCTTCAGGATTACAAGATTCAAAGTGCGCTGCTGGTGCCAACCCTATTCTCCTTCTTCGCCAAAAGCACTCTGATTGACAAATACGATTTATCTAATTTACACGAAATTGCTTCTGGTGGCGCTCCCCTCTCTAAGGAAGTCGGGGAAGCGGTTGCCAAGAGGTTCCATCTGCCAGGTATCAGGCAAGGATATGGGCTCACTGAGACTACATCAGCTATTCTGATTACACCCGAGGGGGATGATAAACCGGGCGCGGTCGGTAAAGTTGTTCCATTTTTTGAAGCGAAGGTTGTGGATCTGGATACCGGGAAAACGCTGGGCGTTAATCAAAGAGGCGAACTGTGTGTGAGAGGTCCTATGATTATGTCCGGTTATGTAAACAATCCGGAAGCGACCAACGCCTTGATTGACAAGGATGGATGGCTACATTCTGGAGACATAGCTTACTGGGACGAAGACGAACACTTCTTCATCGTTGACCGCCTGAAGTCTCTGATTAAGTACAAAGGCTATCAGGTGGCTCCCGCTGAATTGGAATCCATCTTGCTCCAACACCCCAACATCTTCGACGCAGGTGTCGCAGGTCTTCCCGACGATGACGCCGGTGAACTTCCCGCCGCCGTTGTTGTTTTGGAGCACGGAAAGACGATGACGGAAAAAGAGATCGTGGATTACGTCGCCAGTCAAGTAACAACCGCGAAAAAGTTGCGCGGAGGAGTTGTGTTTGTGGACGAAGTACCGAAAGGTCTTACCGGAAAACTCGACGCAAGAAAAATCAGAGAGATCCTCATAAAGGCCAAGAAGGGCGGAAAGATCGCCGTGTAA",
+        source="library",
+        has_start_codon=True,
+        has_stop_codon=True,
+    ))
+
+    # mCherry - red fluorescent protein
+    parts.append(CDSPart(
+        name="mCherry_CDS",
+        sequence="ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA",
+        source="library",
+        has_start_codon=True,
+        has_stop_codon=True,
+    ))
+
+    # Short peptide tag - His6 tag
+    parts.append(CDSPart(
+        name="His6_Tag",
+        sequence="ATGCATCATCATCATCATCATTAA",
+        source="library",
+        has_start_codon=True,
+        has_stop_codon=True,
+    ))
+
+    # ── 3' UTRs ───────────────────────────────────────────────────────────────
+
+    # β-globin 3'UTR - very stable
+    parts.append(UTR3Part(
+        name="β-globin_3UTR",
+        sequence="CTGACTTTCTGCCTTTCCCTGGGCTTTTGCTACCCTTGTTGCCTTTTGGCGTCTTCCTTGCCTTCCTTCTGGTTGGTTTTTCCTCTTGTTGATGCTATGGATCCGCTGCATTAATGAATCGGCCAACGCGCGGGGAGAGGCGGTTTGCGTATTGGGCGCTCTTCCGCTTCCTCGCTCACTGACTCGCTGCGCTCGGTCGTTCGGCTGCGGCGAGCGGTATCAGCTCACTCAAAGGCGGTAATACGGTTATCCACAGAATCAGGGGATAACGCAGGAAAGAACATGTGAGCAAAAGGCCAGCAAAAGGCCAGGAACCGTAAAAAGGCCGCGTTGCTGGCGTTTTTCCATAGGCTCCGCCCCCCTGACGAGCATCACAAAAATCGACGCTCAAGTCAGAGGTGGCGAAACCCGACAGGACTATAAAGATACCAGGCGTTTCCCCCTGGAAGCTCCCTCGTGCGCTCTCCTGTTCCGACCCTGCCGCTTACCGGATACCTGTCCGCCTTTCTCCCTTCGGGAAGCGTGGCGCTTTCTCATAGCTCACGCTGTAGGTATCTCAGTTCGGTGTAGGTCGTTCGCTCCAAGCTGGGCTGTGTGCACGAACCCCCCGTTCAGCCCGACCGCTGCGCCTTATCCGGTAACTATCGTCTTGAGTCCAACCCGGTAAGACACGACTTATCGCCACTGGCAGCAGCCACTGGTAACAGGATTAGCAGAGCGAGGTATGTAGGCGGTGCTACAGAGTTCTTGAAGTGGTGGCCTAACTACGGCTACACTAGAAGAACAGTATTTGGTATCTGCGCTCTGCTGAAGCCAGTTACCTTCGGAAAAAGAGTTGGTAGCTCTTGATCCGGCAAACAAACCACCGCTGGTAGCGGTGGTTTTTTTGTTTGCAAGCAGCAGATTACGCGCAGAAAAAAAGGATCTCAAGAAGATCCTTTGATCTTTTCTACGGGGTCTGACGCTCAGTGGAACGAAAACTCACGTTAAGGGATTTTGGTCATGAGATTATCAAAAAGGATCTTCACCTAGATCCTTTTAAATTAAAAATGAAGTTTTAAATCAATCTAAAGTATATATGAGTAAACTTGGTCTGACAGTTACCAATGCTTAATCAGTGAGGCACCTATCTCAGCGATCTGTCTATTTCGTTCATCCATAGTTGCCTGACTCCCCGTCGTGTAGATAACTACGATACGGGAGGGCTTACCATCTGGCCCCAGTGCTGCAATGATACCGCGAGACCCACGCTCACCGGCTCCAGATTTATCAGCAATAAACCAGCCAGCCGGAAGGGCCGAGCGCAGAAGTGGTCCTGCAACTTTATCCGCCTCCATCCAGTCTATTAATTGTTGCCGGGAAGCTAGAGTAAGTAGTTCGCCAGTTAATAGTTTGCGCAACGTTGTTGCCATTGCTACAGGCATCGTGGTGTCACGCTCGTCGTTTGGTATGGCTTCATTCAGCTCCGGTTCCCAACGATCAAGGCGAGTTACATGATCCCCCATGTTGTGCAAAAAAGCGGTTAGCTCCTTCGGTCCTCCGATCGTTGTCAGAAGTAAGTTGGCCGCAGTGTTATCACTCATGGTTATGGCAGCACTGCATAATTCTCTTACTGTCATGCCATCCGTAAGATGCTTTTCTGTGACTGGTGAGTACTCAACCAAGTCATTCTGAGAATAGTGTATGCGGCGACCGAGTTGCTCTTGCCCGGCGTCAATACGGGATAATACCGCGCCACATAGCAGAACTTTAAAAGTGCTCATCATTGGAAAACGTTCTTCGGGGCGAAAACTCTCAAGGATCTTACCGCTGTTGAGATCCAGTTCGATGTAACCCACTCGTGCACCCAACTGATCTTCAGCATCTTTTACTTTCACCAGCGTTTCTGGGTGAGCAAAAACAGGAAGGCAAAATGCCGCAAAAAAGGGAATAAGGGCGACACGGAAATGTTGAATACTCATACTCTTCCTTTTTCAATATTATTGAAGCATTTATCAGGGTTATTGTCTCATGAGCGGATACATATTTGAATGTATTTAGAAAAATAAACAAATAGGGGTTCCGCGCACATTTCCCCGAAAAGTGCCACCTGACGTC",
+        source="library",
+    ))
+
+    # SV40 polyA signal (short)
+    parts.append(UTR3Part(
+        name="SV40_3UTR",
+        sequence="GATCCAGACATGATAAGATACATTGATGAGTTTGGACAAACCACAACTAGAATGCAGTGAAAAAAATGCTTTATTTGTGAAATTTGTGATGCTATTGCTTTATTTGTAACCATTATAAGCTGCAATAAACAAGTTAACAACAACAATTGCATTCATTTTATGTTTCAGGTTCAGGGGGAGGTGTGGGAGGTTTTTTAAAGCAAGTAAAACCTCTACAAATGTGGTA",
+        source="library",
+    ))
+
+    # Human Growth Hormone 3'UTR
+    parts.append(UTR3Part(
+        name="hGH_3UTR",
+        sequence="CTCGAGGTCGACGGTATCGATAAGCTTGATATCGAATTCCTGCAGCCCGGGGGATCCACTAGTTCTAGAGCGGCCGCCACCGCGGTGGAGCTCCAGCTTTTGTTCCCTTTAGTGAGGGTTAATTGCGCGCTTGGCGTAATCATGGTCATAGCTGTTTCCTGTGTGAAATTGTTATCCGCTCACAATTCCACACAACATACGAGCCGGAAGCATAAAGTGTAAAGCCTGGGGTGCCTAATGAGTGAGCTAACTCACATTAATTGCGTTGCGCTCACTGCCCGCTTTCCAGTCGGGAAACCTGTCGTGCCAGCTGCATTAATGAATCGGCCAACGCGCGGGGAGAGGCGGTTTGCGTATTGGGCGCTCTTCCGCTTCCTCGCTCACTGACTCGCTGCGCTCGGTCGTTCGGCTGCGGCGAGCGGTATCAGCTCACTCAAAGGCGGTAATACGGTTATCCACAGAATCAGGGGATAACGCAGGAAAGAACATGTGAGCAAAAGGCCAGCAAAAGGCCAGGAACCGTAAAAAGGCCGCGTTGCTGGCGTTTTTCCATAGGCTCCGCCCCCCTGACGAGCATCACAAAAATCGACGCTCAAGTCAGAGGTGGCGAAACCCGACAGGACTATAAAGATACCAGGCGTTTCCCCCTGGAAGCTCCCTCGTGCGCTCTCCTGTTCCGACCCTGCCGCTTACCGGATACCTGTCCGCCTTTCTCCCTTCGGGAAGCGTGGCGCTTTCTCATAGCTCACGCTGTAGGTATCTCAGTTCGGTGTAGGTCGTTCGCTCCAAGCTGGGCTGTGTGCACGAACCCCCCGTTCAGCCCGACCGCTGCGCCTTATCCGGTAACTATCGTCTTGAGTCCAACCCGGTAAGACACGACTTATCGCCACTGG",
+        source="library",
+    ))
+
+    # Albumin 3'UTR
+    parts.append(UTR3Part(
+        name="Albumin_3UTR",
+        sequence="TGCCTGGCACTTGTCCCGAACAGTTGGGGGAGGGGAGGGAGTAGGTTGTGTGTGTTGGG",
+        source="library",
+    ))
+
+    # ── Poly(A) tails ─────────────────────────────────────────────────────────
+
+    # Standard 30A tail
+    parts.append(PolyAPart(
+        name="PolyA_30",
+        sequence="A" * 30,
+        source="library",
+        tail_length=30,
+        purity=1.0,
+    ))
+
+    # Long 60A tail
+    parts.append(PolyAPart(
+        name="PolyA_60",
+        sequence="A" * 60,
+        source="library",
+        tail_length=60,
+        purity=1.0,
+    ))
+
+    # Standard 120A tail (typical for mRNA)
+    parts.append(PolyAPart(
+        name="PolyA_120",
+        sequence="A" * 120,
+        source="library",
+        tail_length=120,
+        purity=1.0,
+    ))
+
+    # Short 15A tail
+    parts.append(PolyAPart(
+        name="PolyA_15",
+        sequence="A" * 15,
+        source="library",
+        tail_length=15,
+        purity=1.0,
+    ))
+
+    # Mixed tail (A-rich but not pure)
+    parts.append(PolyAPart(
+        name="PolyA_Mixed_50",
+        sequence="AAAAAAAAACAAAAAAAAAACAAAAAAAAAACAAAAAAAAAACAAAAAAAAAA",
+        source="library",
+        tail_length=50,
+        purity=0.94,
+    ))
+
+    return parts

core/database/__init__.py

@@ -0,0 +1,42 @@
+"""Database connectors and schema mapper."""
+from core.database.base import (
+    ConnectionConfig,
+    DatabaseConnector,
+    FieldMapping,
+    SchemaMapper,
+    SEQUENCE_FIELDS,
+)
+from core.database.sqlite import SQLiteConnector
+from core.database.postgres import PostgreSQLConnector
+from core.database.csv_importer import CSVConnector
+
+
+def create_connector(config: ConnectionConfig) -> DatabaseConnector:
+    """Factory: return the appropriate connector for config.backend."""
+    backends = {
+        "sqlite": SQLiteConnector,
+        "postgres": PostgreSQLConnector,
+        "postgresql": PostgreSQLConnector,
+        "csv": CSVConnector,
+        "excel": CSVConnector,
+    }
+    cls = backends.get(config.backend.lower())
+    if cls is None:
+        raise ValueError(
+            f"Unknown backend '{config.backend}'. "
+            f"Supported: {list(backends.keys())}"
+        )
+    return cls(config)
+
+
+__all__ = [
+    "ConnectionConfig",
+    "DatabaseConnector",
+    "FieldMapping",
+    "SchemaMapper",
+    "SEQUENCE_FIELDS",
+    "SQLiteConnector",
+    "PostgreSQLConnector",
+    "CSVConnector",
+    "create_connector",
+]

core/database/base.py

@@ -0,0 +1,204 @@
+"""
+Abstract database connector interface and SchemaMapper.
+
+Every database backend (SQLite, PostgreSQL, CSV) implements DatabaseConnector.
+SchemaMapper translates arbitrary column names to the mRNASequence model fields.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from core.models.sequence import mRNASequence
+
+
+# Fields in mRNASequence that can be mapped from a database
+SEQUENCE_FIELDS = {
+    "name",
+    "five_prime_utr",
+    "kozak",
+    "cds",
+    "three_prime_utr",
+    "poly_a",
+    "full_mrna",
+}
+
+
+@dataclass
+class ConnectionConfig:
+    """Generic connection configuration (fields vary by backend)."""
+    backend: str                        # "sqlite", "postgres", "csv", "excel"
+    display_name: str                   # User-facing label for the connection
+    params: Dict[str, Any] = field(default_factory=dict)
+    # e.g. sqlite: {"path": "/data/seqs.db"}
+    # e.g. postgres: {"host": "...", "port": 5432, "dbname": "...", "user": "...", "password": "..."}
+    # e.g. csv: {"path": "/data/seqs.csv"}
+
+
+class DatabaseConnector(ABC):
+    """Abstract database connector. One instance per active connection."""
+
+    def __init__(self, config: ConnectionConfig) -> None:
+        self.config = config
+        self._connected = False
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Open the connection. Raises ConnectionError on failure."""
+        ...
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close the connection."""
+        ...
+
+    @abstractmethod
+    def list_tables(self) -> List[str]:
+        """Return available table / sheet names."""
+        ...
+
+    @abstractmethod
+    def get_records(
+        self,
+        table: str,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """
+        Fetch records from a table.
+
+        Parameters
+        ----------
+        table : str
+            Table name (from list_tables).
+        query : str, optional
+            Backend-specific filter string (SQL WHERE clause for SQL backends,
+            pandas query string for file backends).
+        limit : int, optional
+            Max rows to return.
+        """
+        ...
+
+    @abstractmethod
+    def get_columns(self, table: str) -> List[str]:
+        """Return column names for a table."""
+        ...
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    @property
+    def name(self) -> str:
+        return self.config.display_name
+
+    def __repr__(self) -> str:
+        status = "connected" if self._connected else "disconnected"
+        return f"{self.__class__.__name__}({self.name!r}, {status})"
+
+
+# ── Schema Mapper ────────────────────────────────────────────────────────────
+
+@dataclass
+class FieldMapping:
+    """
+    Describes how one database column maps to a mRNASequence field.
+
+    source_column : str
+        Column name in the database.
+    target_field : str
+        Field name in mRNASequence. Must be in SEQUENCE_FIELDS.
+    transform : callable, optional
+        Optional transform applied to the raw value before assignment.
+        E.g. str.upper, lambda x: x.replace(" ", "")
+    """
+    source_column: str
+    target_field: str
+    transform: Optional[Any] = None   # callable or None
+
+    def __post_init__(self) -> None:
+        if self.target_field not in SEQUENCE_FIELDS:
+            raise ValueError(
+                f"'{self.target_field}' is not a valid mRNASequence field. "
+                f"Valid fields: {sorted(SEQUENCE_FIELDS)}"
+            )
+
+
+class SchemaMapper:
+    """
+    Maps a DataFrame (from any DatabaseConnector) to a list of mRNASequence
+    objects using a user-configured field mapping.
+
+    Example
+    -------
+    mapper = SchemaMapper([
+        FieldMapping("mrna_sequence", "full_mrna"),
+        FieldMapping("gene_name", "name"),
+        FieldMapping("utr5_sequence", "five_prime_utr", transform=str.upper),
+    ])
+    sequences = mapper.map_dataframe(df, db_source="my_lims")
+    """
+
+    def __init__(self, mappings: List[FieldMapping], db_source: str = "") -> None:
+        self.mappings = mappings
+        self.db_source = db_source
+        # Validate: exactly one mapping targeting 'name' must exist
+        name_targets = [m for m in mappings if m.target_field == "name"]
+        if not name_targets:
+            raise ValueError(
+                "SchemaMapper requires at least one FieldMapping targeting 'name'."
+            )
+
+    def map_row(self, row: Dict[str, Any]) -> mRNASequence:
+        """Map a single row dict to an mRNASequence."""
+        kwargs: Dict[str, Any] = {
+            "source": "database",
+            "db_source": self.db_source,
+            "raw_metadata": dict(row),
+        }
+        for mapping in self.mappings:
+            value = row.get(mapping.source_column)
+            # Skip None and NaN values (pandas often returns NaN for SQL NULL)
+            if value is None or (isinstance(value, float) and pd.isna(value)):
+                continue
+            if mapping.transform is not None:
+                try:
+                    value = mapping.transform(value)
+                except Exception:
+                    pass
+            kwargs[mapping.target_field] = value
+        # name is required — fall back to first non-empty string value in the row
+        if "name" not in kwargs or not kwargs["name"]:
+            for v in row.values():
+                if isinstance(v, str) and v.strip():
+                    kwargs["name"] = v.strip()[:80]
+                    break
+            else:
+                kwargs["name"] = "unnamed"
+        return mRNASequence(**kwargs)  # type: ignore[arg-type]
+
+    def map_dataframe(self, df: pd.DataFrame) -> List[mRNASequence]:
+        """Map every row in df to an mRNASequence."""
+        return [self.map_row(row.to_dict()) for _, row in df.iterrows()]
+
+    @classmethod
+    def from_dict(cls, mapping_dict: Dict[str, str], db_source: str = "") -> "SchemaMapper":
+        """
+        Convenience constructor from a plain {db_column: sequence_field} dict.
+
+        Example
+        -------
+        mapper = SchemaMapper.from_dict({
+            "gene_name": "name",
+            "mrna_seq": "full_mrna",
+            "utr": "five_prime_utr",
+        })
+        """
+        mappings = [
+            FieldMapping(source_column=col, target_field=field_)
+            for col, field_ in mapping_dict.items()
+        ]
+        return cls(mappings, db_source=db_source)

core/database/csv_importer.py

@@ -0,0 +1,97 @@
+"""CSV and Excel flat-file connector."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import pandas as pd
+
+from core.database.base import ConnectionConfig, DatabaseConnector
+
+
+class CSVConnector(DatabaseConnector):
+    """
+    Connector for CSV and Excel flat files.
+
+    For CSV: treats the single file as one 'table' named by the filename stem.
+    For Excel: each worksheet is a 'table'.
+    A directory of CSV files is also supported — each file becomes a table.
+    """
+
+    def __init__(self, config: ConnectionConfig) -> None:
+        super().__init__(config)
+        self._dataframes: Dict[str, pd.DataFrame] = {}
+
+    def connect(self) -> None:
+        path_str = self.config.params.get("path")
+        if not path_str:
+            raise ValueError("CSV/Excel config must include 'path'.")
+        path = Path(path_str)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        self._dataframes = {}
+
+        if path.is_dir():
+            # Load all CSVs in directory
+            for csv_file in sorted(path.glob("*.csv")):
+                df = pd.read_csv(csv_file)
+                self._dataframes[csv_file.stem] = df
+            if not self._dataframes:
+                raise ValueError(f"No CSV files found in directory: {path}")
+
+        elif path.suffix.lower() in (".xlsx", ".xls"):
+            xl = pd.ExcelFile(path)
+            for sheet in xl.sheet_names:
+                self._dataframes[sheet] = xl.parse(sheet)
+
+        elif path.suffix.lower() == ".csv":
+            df = pd.read_csv(path)
+            self._dataframes[path.stem] = df
+
+        else:
+            raise ValueError(
+                f"Unsupported file type: {path.suffix}. Use .csv, .xlsx, or .xls."
+            )
+
+        self._connected = True
+
+    def disconnect(self) -> None:
+        self._dataframes.clear()
+        self._connected = False
+
+    def list_tables(self) -> List[str]:
+        return list(self._dataframes.keys())
+
+    def get_columns(self, table: str) -> List[str]:
+        self._require_connected()
+        df = self._get_table(table)
+        return list(df.columns)
+
+    def get_records(
+        self,
+        table: str,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        self._require_connected()
+        df = self._get_table(table).copy()
+        if query:
+            try:
+                df = df.query(query)
+            except Exception as e:
+                raise ValueError(f"Query error: {e}") from e
+        if limit:
+            df = df.head(limit)
+        return df.reset_index(drop=True)
+
+    def _get_table(self, table: str) -> pd.DataFrame:
+        if table not in self._dataframes:
+            raise KeyError(
+                f"Table '{table}' not found. Available: {self.list_tables()}"
+            )
+        return self._dataframes[table]
+
+    def _require_connected(self) -> None:
+        if not self._connected:
+            raise RuntimeError("Not connected. Call connect() first.")

core/database/postgres.py

@@ -0,0 +1,81 @@
+"""PostgreSQL database connector (via SQLAlchemy + psycopg2)."""
+from __future__ import annotations
+
+from typing import List, Optional
+
+import pandas as pd
+from sqlalchemy import create_engine, inspect, text
+from sqlalchemy.engine import Engine
+
+from core.database.base import ConnectionConfig, DatabaseConnector
+
+
+class PostgreSQLConnector(DatabaseConnector):
+    """Connects to a PostgreSQL database."""
+
+    def __init__(self, config: ConnectionConfig) -> None:
+        super().__init__(config)
+        self._engine: Optional[Engine] = None
+
+    def _build_url(self) -> str:
+        p = self.config.params
+        user = p.get("user", "")
+        password = p.get("password", "")
+        host = p.get("host", "localhost")
+        port = p.get("port", 5432)
+        dbname = p.get("dbname", "")
+        if password:
+            return f"postgresql+psycopg2://{user}:{password}@{host}:{port}/{dbname}"
+        return f"postgresql+psycopg2://{user}@{host}:{port}/{dbname}"
+
+    def connect(self) -> None:
+        try:
+            url = self._build_url()
+            self._engine = create_engine(url, pool_pre_ping=True)
+            # Test the connection
+            with self._engine.connect() as conn:
+                conn.execute(text("SELECT 1"))
+            self._connected = True
+        except Exception as e:
+            raise ConnectionError(f"PostgreSQL connection failed: {e}") from e
+
+    def disconnect(self) -> None:
+        if self._engine:
+            self._engine.dispose()
+            self._engine = None
+        self._connected = False
+
+    def list_tables(self) -> List[str]:
+        self._require_connected()
+        inspector = inspect(self._engine)
+        return inspector.get_table_names()
+
+    def get_columns(self, table: str) -> List[str]:
+        self._require_connected()
+        inspector = inspect(self._engine)
+        return [col["name"] for col in inspector.get_columns(table)]
+
+    def get_records(
+        self,
+        table: str,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        self._require_connected()
+        sql = f'SELECT * FROM "{table}"'
+        if query:
+            sql += f" WHERE {query}"
+        if limit:
+            sql += f" LIMIT {limit}"
+        with self._engine.connect() as conn:  # type: ignore[union-attr]
+            return pd.read_sql_query(text(sql), conn)
+
+    def execute_raw(self, sql: str) -> pd.DataFrame:
+        """Run arbitrary read-only SQL."""
+        self._require_connected()
+        with self._engine.connect() as conn:  # type: ignore[union-attr]
+            return pd.read_sql_query(text(sql), conn)
+
+    def _require_connected(self) -> None:
+        if not self._connected or self._engine is None:
+            raise RuntimeError("Not connected. Call connect() first.")

core/database/sqlite.py

@@ -0,0 +1,68 @@
+"""SQLite database connector."""
+from __future__ import annotations
+
+import sqlite3
+from typing import List, Optional
+
+import pandas as pd
+
+from core.database.base import ConnectionConfig, DatabaseConnector
+
+
+class SQLiteConnector(DatabaseConnector):
+    """Connects to a local SQLite database file."""
+
+    def __init__(self, config: ConnectionConfig) -> None:
+        super().__init__(config)
+        self._conn: Optional[sqlite3.Connection] = None
+
+    def connect(self) -> None:
+        path = self.config.params.get("path")
+        if not path:
+            raise ValueError("SQLite config must include 'path'.")
+        try:
+            self._conn = sqlite3.connect(path, check_same_thread=False)
+            self._connected = True
+        except sqlite3.Error as e:
+            raise ConnectionError(f"SQLite connection failed: {e}") from e
+
+    def disconnect(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+        self._connected = False
+
+    def list_tables(self) -> List[str]:
+        self._require_connected()
+        cursor = self._conn.execute(  # type: ignore[union-attr]
+            "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;"
+        )
+        return [row[0] for row in cursor.fetchall()]
+
+    def get_columns(self, table: str) -> List[str]:
+        self._require_connected()
+        cursor = self._conn.execute(f'PRAGMA table_info("{table}");')  # type: ignore[union-attr]
+        return [row[1] for row in cursor.fetchall()]
+
+    def get_records(
+        self,
+        table: str,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        self._require_connected()
+        sql = f'SELECT * FROM "{table}"'
+        if query:
+            sql += f" WHERE {query}"
+        if limit:
+            sql += f" LIMIT {limit}"
+        return pd.read_sql_query(sql, self._conn)  # type: ignore[arg-type]
+
+    def execute_raw(self, sql: str) -> pd.DataFrame:
+        """Run arbitrary read-only SQL and return a DataFrame."""
+        self._require_connected()
+        return pd.read_sql_query(sql, self._conn)  # type: ignore[arg-type]
+
+    def _require_connected(self) -> None:
+        if not self._connected or self._conn is None:
+            raise RuntimeError("Not connected. Call connect() first.")

core/models/parts.py

@@ -0,0 +1,173 @@
+"""
+Sequence part models for the parts library.
+
+SequencePart is the base class; specialized part types inherit to add
+bespoke fields (e.g., CDS has protein_sequence, codon_usage; UTRs have
+stability metrics).
+
+Parts are auto-extracted when sequences are analyzed or imported.
+"""
+from __future__ import annotations
+
+import hashlib
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Optional
+
+
+@dataclass
+class SequencePart:
+    """
+    Base class for reusable sequence parts.
+
+    Each part can be mixed and matched in the Parts Workshop to
+    assemble new mRNA sequences.
+    """
+    name: str
+    sequence: str
+    part_type: Literal["5_utr", "kozak", "cds", "3_utr", "polya"]
+    source: str  # "database_import", "generated", "manual", "extracted"
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    origin_sequence_id: Optional[str] = None  # ID of parent mRNASequence
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def length(self) -> int:
+        return len(self.sequence)
+
+    @property
+    def sequence_hash(self) -> str:
+        """SHA256 hash for deduplication."""
+        return hashlib.sha256(self.sequence.encode()).hexdigest()[:16]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "sequence": self.sequence,
+            "part_type": self.part_type,
+            "source": self.source,
+            "origin_sequence_id": self.origin_sequence_id,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class UTR5Part(SequencePart):
+    """5' UTR part with stability and structure metrics."""
+    part_type: Literal["5_utr"] = field(default="5_utr", init=False)
+
+    # Predicted secondary structure stability
+    stability_score: Optional[float] = None
+    mfe: Optional[float] = None  # Minimum free energy from ViennaRNA
+    secondary_structure_dot: Optional[str] = None  # Dot-bracket notation
+
+
+@dataclass
+class KozakPart(SequencePart):
+    """Kozak consensus sequence part."""
+    part_type: Literal["kozak"] = field(default="kozak", init=False)
+
+    # Consensus score (0-1) based on optimal Kozak pattern
+    consensus_score: Optional[float] = None
+    # Canonical Kozak is: gcc(A/G)ccATGG
+    matches_canonical: Optional[bool] = None
+
+
+@dataclass
+class CDSPart(SequencePart):
+    """Coding sequence part with translation and codon metrics."""
+    part_type: Literal["cds"] = field(default="cds", init=False)
+
+    # Translated protein sequence
+    protein_sequence: Optional[str] = None
+
+    # Codon usage metrics
+    codon_usage: Optional[Dict[str, float]] = None  # {codon: frequency}
+    cai: Optional[float] = None  # Codon Adaptation Index
+
+    # Quality checks
+    has_start_codon: Optional[bool] = None
+    has_stop_codon: Optional[bool] = None
+    in_frame: Optional[bool] = None
+
+
+@dataclass
+class UTR3Part(SequencePart):
+    """3' UTR part with stability and regulatory element annotations."""
+    part_type: Literal["3_utr"] = field(default="3_utr", init=False)
+
+    # Predicted stability
+    stability_score: Optional[float] = None
+    mfe: Optional[float] = None
+
+    # Regulatory elements (AU-rich elements, miRNA binding sites, etc.)
+    regulatory_elements: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class PolyAPart(SequencePart):
+    """Poly(A) tail part."""
+    part_type: Literal["polya"] = field(default="polya", init=False)
+
+    # Length of the poly(A) stretch
+    tail_length: Optional[int] = None
+
+    # Purity (percentage of A nucleotides)
+    purity: Optional[float] = None
+
+
+# Type alias for all part types
+AnyPart = UTR5Part | KozakPart | CDSPart | UTR3Part | PolyAPart
+
+
+def create_part_from_component(
+    sequence: str,
+    part_type: Literal["5_utr", "kozak", "cds", "3_utr", "polya"],
+    name: str,
+    source: str,
+    origin_sequence_id: Optional[str] = None,
+) -> AnyPart:
+    """
+    Factory function to create the appropriate Part subclass.
+
+    Used during auto-extraction from mRNASequence objects.
+    """
+    if part_type == "5_utr":
+        return UTR5Part(
+            name=name,
+            sequence=sequence,
+            source=source,
+            origin_sequence_id=origin_sequence_id,
+        )
+    elif part_type == "kozak":
+        return KozakPart(
+            name=name,
+            sequence=sequence,
+            source=source,
+            origin_sequence_id=origin_sequence_id,
+        )
+    elif part_type == "cds":
+        return CDSPart(
+            name=name,
+            sequence=sequence,
+            source=source,
+            origin_sequence_id=origin_sequence_id,
+        )
+    elif part_type == "3_utr":
+        return UTR3Part(
+            name=name,
+            sequence=sequence,
+            source=source,
+            origin_sequence_id=origin_sequence_id,
+        )
+    elif part_type == "polya":
+        return PolyAPart(
+            name=name,
+            sequence=sequence,
+            source=source,
+            origin_sequence_id=origin_sequence_id,
+        )
+    else:
+        raise ValueError(f"Unknown part type: {part_type}")

core/models/plasmid.py

@@ -0,0 +1,178 @@
+"""
+Plasmid domain models.
+
+Covers plasmid backbones and fully assembled plasmids (backbone + mRNA insert).
+Assembly strategies and junction logic live in core/optimization/assembly.py;
+these are pure data structures.
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Tuple
+
+from core.models.sequence import SequenceAnnotation, mRNASequence
+
+
+@dataclass
+class PlasmidFeature:
+    """A named functional element within a plasmid sequence."""
+    label: str
+    feature_type: Literal[
+        "promoter", "terminator", "ori", "resistance", "tag",
+        "cloning_site", "insert", "utr", "cds", "other"
+    ]
+    start: int       # 0-based, within linear representation
+    end: int
+    strand: Literal["+", "-", "."] = "+"
+    color: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def length(self) -> int:
+        return self.end - self.start
+
+
+@dataclass
+class PlasmidBackbone:
+    """
+    A cloning vector / expression backbone.
+
+    The backbone sequence is stored as linearised DNA. For circular
+    representation in the UI, the sequence wraps end-to-start.
+    cloning_sites lists the restriction enzyme names or recombination
+    sites present (for QC/assembly checks).
+    """
+    name: str
+    sequence: str                             # full circular backbone, linearised
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    description: Optional[str] = None
+
+    # Functional elements (promoters, resistance, ori, MCS, etc.)
+    features: List[PlasmidFeature] = field(default_factory=list)
+
+    # Restriction/recombination sites available for cloning
+    cloning_sites: List[str] = field(default_factory=list)
+
+    # Source: "local", "library", or a db_source name
+    source: str = "local"
+    raw_metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def length(self) -> int:
+        return len(self.sequence)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "sequence": self.sequence,
+            "features": [
+                {
+                    "label": f.label,
+                    "feature_type": f.feature_type,
+                    "start": f.start,
+                    "end": f.end,
+                    "strand": f.strand,
+                    "color": f.color,
+                }
+                for f in self.features
+            ],
+            "cloning_sites": self.cloning_sites,
+            "source": self.source,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PlasmidBackbone":
+        features = [
+            PlasmidFeature(
+                label=f["label"],
+                feature_type=f.get("feature_type", "other"),
+                start=f["start"],
+                end=f["end"],
+                strand=f.get("strand", "+"),
+                color=f.get("color"),
+            )
+            for f in data.get("features", [])
+        ]
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            name=data["name"],
+            description=data.get("description"),
+            sequence=data["sequence"],
+            features=features,
+            cloning_sites=data.get("cloning_sites", []),
+            source=data.get("source", "local"),
+        )
+
+
+@dataclass
+class AssemblyJunction:
+    """
+    Records how two parts are joined in an assembly.
+    Stores the junction sequence added/used, and the strategy that created it.
+    """
+    part_a_name: str
+    part_b_name: str
+    strategy: Literal["restriction", "golden_gate", "gibson", "direct"]
+    junction_sequence: str         # the overhang / overlap / linker added
+    enzyme: Optional[str] = None   # for restriction/GG assemblies
+
+
+@dataclass
+class AssembledPlasmid:
+    """
+    A fully assembled plasmid: backbone + mRNA insert, with provenance.
+
+    full_sequence is the assembled circular sequence as a flat string.
+    junctions records every join point for audit / re-assembly.
+    In QC mode this is populated from the unmodified parts; in Make mode
+    the parts are modified and junctions record what was added.
+    """
+    name: str
+    backbone: PlasmidBackbone
+    insert: mRNASequence
+    assembly_strategy: Literal["restriction", "golden_gate", "gibson"]
+    assembly_mode: Literal["qc", "make"]
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    full_sequence: Optional[str] = None      # None until assembly is run
+    features: List[PlasmidFeature] = field(default_factory=list)
+    junctions: List[AssemblyJunction] = field(default_factory=list)
+    qc_issues: List[str] = field(default_factory=list)   # validation warnings
+    notes: Optional[str] = None
+
+    @property
+    def is_assembled(self) -> bool:
+        return self.full_sequence is not None
+
+    @property
+    def length(self) -> Optional[int]:
+        return len(self.full_sequence) if self.full_sequence else None
+
+    def to_genbank_annotations(self) -> List[Tuple[str, str, int, int, str]]:
+        """
+        Return (label, feature_type, start, end, strand) tuples suitable
+        for writing a GenBank file via BioPython.
+        """
+        return [
+            (f.label, f.feature_type, f.start, f.end, f.strand)
+            for f in self.features
+        ]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "backbone_id": self.backbone.id,
+            "backbone_name": self.backbone.name,
+            "insert_id": self.insert.id,
+            "insert_name": self.insert.name,
+            "assembly_strategy": self.assembly_strategy,
+            "assembly_mode": self.assembly_mode,
+            "full_sequence": self.full_sequence,
+            "qc_issues": self.qc_issues,
+            "notes": self.notes,
+        }

core/models/sequence.py

@@ -0,0 +1,196 @@
+"""
+Core mRNA sequence domain model.
+
+Designed to be flexible: different databases store sequence data differently.
+Some customers have a single 'mrna_sequence' field; others split into UTR/CDS/PolyA.
+The SchemaMapper normalizes those into this model.
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional
+
+
+@dataclass
+class SequenceAnnotation:
+    """A named region within a sequence (0-based, half-open [start, end))."""
+    label: str
+    start: int
+    end: int
+    strand: Literal["+", "-", "."] = "+"
+    color: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def length(self) -> int:
+        return self.end - self.start
+
+
+@dataclass
+class mRNASequence:
+    """
+    Core mRNA sequence model.
+
+    Components are all optional because different databases represent
+    sequence data at different granularities. assembled_sequence will
+    concatenate whichever components are present, or return full_mrna
+    if the database provides the complete sequence as a single field.
+    """
+    name: str
+    source: Literal["local", "database"]
+
+    # Auto-generated unique identifier
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+    # Which database connection this came from (None for local sequences)
+    db_source: Optional[str] = None
+
+    # ── Sequence components (all optional) ──────────────────────────────────
+    # Stored as DNA (T not U) for computational convenience; displayed as RNA
+    five_prime_utr: Optional[str] = None
+    kozak: Optional[str] = None
+    cds: Optional[str] = None
+    three_prime_utr: Optional[str] = None
+    poly_a: Optional[str] = None
+
+    # Full pre-assembled sequence from DB (when component breakdown is unavailable)
+    full_mrna: Optional[str] = None
+
+    # Annotations populated by analysis or DB import
+    annotations: List[SequenceAnnotation] = field(default_factory=list)
+
+    # Raw database record — all original fields preserved for model use
+    raw_metadata: Dict[str, Any] = field(default_factory=dict)
+
+    # Analysis cache — populated lazily by SequenceAnalyzer
+    _analysis_cache: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    # ── Derived properties ──────────────────────────────────────────────────
+
+    @property
+    def assembled_sequence(self) -> str:
+        """
+        Return the full sequence by concatenating present components.
+        Falls back to full_mrna if no components are set.
+        Raises ValueError if neither is available.
+        """
+        parts = [
+            self.five_prime_utr or "",
+            self.kozak or "",
+            self.cds or "",
+            self.three_prime_utr or "",
+            self.poly_a or "",
+        ]
+        assembled = "".join(parts)
+        if assembled:
+            return assembled.upper()
+        if self.full_mrna:
+            return self.full_mrna.upper()
+        raise ValueError(
+            f"Sequence '{self.name}' has no components and no full_mrna set."
+        )
+
+    @property
+    def has_components(self) -> bool:
+        """True if at least one sub-component is explicitly set."""
+        return any([
+            self.five_prime_utr,
+            self.kozak,
+            self.cds,
+            self.three_prime_utr,
+            self.poly_a,
+        ])
+
+    @property
+    def component_annotations(self) -> List[SequenceAnnotation]:
+        """
+        Auto-derive position annotations from the component breakdown.
+        Only available when has_components is True.
+        """
+        annotations = []
+        pos = 0
+        component_colors = {
+            "5'UTR": "#4A90D9",
+            "Kozak": "#F5A623",
+            "CDS": "#7ED321",
+            "3'UTR": "#9B59B6",
+            "PolyA": "#E74C3C",
+        }
+        components = [
+            ("5'UTR", self.five_prime_utr),
+            ("Kozak", self.kozak),
+            ("CDS", self.cds),
+            ("3'UTR", self.three_prime_utr),
+            ("PolyA", self.poly_a),
+        ]
+        for label, seq in components:
+            if seq:
+                annotations.append(SequenceAnnotation(
+                    label=label,
+                    start=pos,
+                    end=pos + len(seq),
+                    color=component_colors.get(label),
+                ))
+                pos += len(seq)
+        return annotations
+
+    @property
+    def length(self) -> int:
+        try:
+            return len(self.assembled_sequence)
+        except ValueError:
+            return 0
+
+    @property
+    def cds_length(self) -> Optional[int]:
+        return len(self.cds) if self.cds else None
+
+    # ── Mutation helpers ──────────────────────────���─────────────────────────
+
+    def with_cds(self, cds: str) -> "mRNASequence":
+        """Return a new mRNASequence with the CDS replaced."""
+        from dataclasses import replace
+        return replace(
+            self,
+            id=str(uuid.uuid4()),
+            cds=cds.upper(),
+            source="local",
+            db_source=None,
+            _analysis_cache={},
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "source": self.source,
+            "db_source": self.db_source,
+            "five_prime_utr": self.five_prime_utr,
+            "kozak": self.kozak,
+            "cds": self.cds,
+            "three_prime_utr": self.three_prime_utr,
+            "poly_a": self.poly_a,
+            "full_mrna": self.full_mrna,
+            "raw_metadata": self.raw_metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "mRNASequence":
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            name=data["name"],
+            source=data.get("source", "local"),
+            db_source=data.get("db_source"),
+            five_prime_utr=data.get("five_prime_utr"),
+            kozak=data.get("kozak"),
+            cds=data.get("cds"),
+            three_prime_utr=data.get("three_prime_utr"),
+            poly_a=data.get("poly_a"),
+            full_mrna=data.get("full_mrna"),
+            raw_metadata=data.get("raw_metadata", {}),
+        )
+
+    def __repr__(self) -> str:
+        length = self.length
+        return f"mRNASequence(name={self.name!r}, source={self.source!r}, length={length})"

core/models/worklist.py

@@ -0,0 +1,159 @@
+"""
+Worklist domain model.
+
+A Worklist is the user's active work queue — a curated collection of
+sequences they want to analyze, score, assemble, or export.
+
+Items can originate from three sources:
+  - database_import  : selected rows from a DB connector
+  - generated        : output of a generative model or genetic algorithm
+  - cds_optimized    : protein sequence → optimized CDS + UTR selection
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterator, List, Literal, Optional
+
+from core.models.sequence import mRNASequence
+
+
+ItemOrigin = Literal["database_import", "generated", "cds_optimized", "manual"]
+ItemStatus = Literal["pending", "analyzing", "analyzed", "error"]
+
+
+@dataclass
+class WorklistItem:
+    """
+    A single entry in the worklist.
+
+    scores: populated by model runners — {model_name: score}
+    analysis: populated by SequenceAnalyzer — {metric_name: value}
+    """
+    sequence: mRNASequence
+    origin: ItemOrigin
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    status: ItemStatus = "pending"
+    added_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    # Scoring results — keyed by model name
+    scores: Dict[str, float] = field(default_factory=dict)
+
+    # Analysis results — support multiple analyses
+    # Structure: {analysis_name: {metric: value, ...}}
+    # - "base_analysis": core sequence metrics (GC%, CAI, etc.)
+    # - model/analysis names: custom analysis results
+    analyses: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+
+    # Notes / tags
+    notes: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return self.sequence.name
+
+    @property
+    def has_scores(self) -> bool:
+        return bool(self.scores)
+
+    @property
+    def has_analyses(self) -> bool:
+        return bool(self.analyses)
+
+    @property
+    def base_analysis(self) -> Optional[Dict[str, Any]]:
+        """Quick accessor for base sequence analysis results."""
+        return self.analyses.get("base_analysis")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "sequence_id": self.sequence.id,
+            "sequence_name": self.sequence.name,
+            "origin": self.origin,
+            "status": self.status,
+            "added_at": self.added_at.isoformat(),
+            "scores": self.scores,
+            "notes": self.notes,
+            "tags": self.tags,
+        }
+
+
+@dataclass
+class Worklist:
+    """
+    The user's active sequence work queue.
+
+    Provides list-like access to WorklistItems with helpers for
+    filtering by origin, status, and tags.
+    """
+    name: str = "Untitled Worklist"
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    items: List[WorklistItem] = field(default_factory=list)
+
+    # ── Mutation ────────────────────────────────────────────────────────────
+
+    def add(self, sequence: mRNASequence, origin: ItemOrigin = "manual") -> WorklistItem:
+        """Add a sequence and return the new WorklistItem."""
+        item = WorklistItem(sequence=sequence, origin=origin)
+        self.items.append(item)
+        return item
+
+    def add_many(
+        self,
+        sequences: List[mRNASequence],
+        origin: ItemOrigin = "manual",
+    ) -> List[WorklistItem]:
+        return [self.add(seq, origin) for seq in sequences]
+
+    def remove(self, item_id: str) -> bool:
+        """Remove item by id. Returns True if found and removed."""
+        before = len(self.items)
+        self.items = [i for i in self.items if i.id != item_id]
+        return len(self.items) < before
+
+    def clear(self) -> None:
+        self.items.clear()
+
+    # ── Query ────────────────────────────────────────────────────────────────
+
+    def get(self, item_id: str) -> Optional[WorklistItem]:
+        return next((i for i in self.items if i.id == item_id), None)
+
+    def by_origin(self, origin: ItemOrigin) -> List[WorklistItem]:
+        return [i for i in self.items if i.origin == origin]
+
+    def by_status(self, status: ItemStatus) -> List[WorklistItem]:
+        return [i for i in self.items if i.status == status]
+
+    def with_tag(self, tag: str) -> List[WorklistItem]:
+        return [i for i in self.items if tag in i.tags]
+
+    def scored(self, model_name: Optional[str] = None) -> List[WorklistItem]:
+        """Items that have scores. Filter by model_name if given."""
+        if model_name:
+            return [i for i in self.items if model_name in i.scores]
+        return [i for i in self.items if i.scores]
+
+    # ── Properties ──────────────────────────────────────────────────────────
+
+    @property
+    def count(self) -> int:
+        return len(self.items)
+
+    @property
+    def sequences(self) -> List[mRNASequence]:
+        return [i.sequence for i in self.items]
+
+    def __iter__(self) -> Iterator[WorklistItem]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __repr__(self) -> str:
+        return f"Worklist(name={self.name!r}, count={self.count})"

core/sequence_tools/clean_for_cloning.py

@@ -0,0 +1,172 @@
+"""
+Clean for Cloning — prepare sequences for insertion into cloning vectors.
+
+Performs synonymous codon substitutions to remove problematic elements:
+- Internal restriction sites matching the cloning enzyme
+- Homopolymer runs exceeding max length
+- Stop codon replacement / double stop codon addition
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from core.analysis.restriction_sites import scan_restriction_sites
+from core.analysis.homopolymers import detect_homopolymers
+
+
+# Genetic code: codon -> amino acid
+CODON_TABLE = {
+    "TTT": "F", "TTC": "F", "TTA": "L", "TTG": "L",
+    "CTT": "L", "CTC": "L", "CTA": "L", "CTG": "L",
+    "ATT": "I", "ATC": "I", "ATA": "I", "ATG": "M",
+    "GTT": "V", "GTC": "V", "GTA": "V", "GTG": "V",
+    "TCT": "S", "TCC": "S", "TCA": "S", "TCG": "S",
+    "CCT": "P", "CCC": "P", "CCA": "P", "CCG": "P",
+    "ACT": "T", "ACC": "T", "ACA": "T", "ACG": "T",
+    "GCT": "A", "GCC": "A", "GCA": "A", "GCG": "A",
+    "TAT": "Y", "TAC": "Y", "TAA": "*", "TAG": "*",
+    "CAT": "H", "CAC": "H", "CAA": "Q", "CAG": "Q",
+    "AAT": "N", "AAC": "N", "AAA": "K", "AAG": "K",
+    "GAT": "D", "GAC": "D", "GAA": "E", "GAG": "E",
+    "TGT": "C", "TGC": "C", "TGA": "*", "TGG": "W",
+    "CGT": "R", "CGC": "R", "CGA": "R", "CGG": "R",
+    "AGT": "S", "AGC": "S", "AGA": "R", "AGG": "R",
+    "GGT": "G", "GGC": "G", "GGA": "G", "GGG": "G",
+}
+
+# Reverse: amino acid -> list of codons
+AA_TO_CODONS: Dict[str, List[str]] = {}
+for codon, aa in CODON_TABLE.items():
+    AA_TO_CODONS.setdefault(aa, []).append(codon)
+
+
+@dataclass
+class CleaningResult:
+    """Result of sequence cleaning operation."""
+    original: str
+    cleaned: str
+    changes: List[str] = field(default_factory=list)
+    restriction_sites_removed: int = 0
+    homopolymers_shortened: int = 0
+    stop_codon_changed: bool = False
+    double_stop_added: bool = False
+    adapters_added: bool = False
+
+
+def clean_for_cloning(
+    cds: str,
+    enzymes_to_avoid: Optional[List[str]] = None,
+    preferred_stop: str = "TAA",
+    use_double_stop: bool = True,
+    max_homopolymer: int = 6,
+    remove_homopolymers: bool = True,
+    add_5_adapter: str = "",
+    add_3_adapter: str = "",
+) -> CleaningResult:
+    """
+    Clean a CDS for cloning by removing problematic elements.
+
+    Parameters
+    ----------
+    cds : str
+        Coding DNA sequence.
+    enzymes_to_avoid : list of str
+        Restriction enzymes whose sites should be silently removed.
+    preferred_stop : str
+        Preferred stop codon (TAA, TAG, TGA).
+    use_double_stop : bool
+        Append a second stop codon.
+    max_homopolymer : int
+        Maximum allowed homopolymer run length.
+    remove_homopolymers : bool
+        Whether to break up homopolymer runs.
+    add_5_adapter : str
+        Sequence to prepend.
+    add_3_adapter : str
+        Sequence to append.
+
+    Returns
+    -------
+    CleaningResult
+    """
+    seq = cds.upper().replace("U", "T")
+    changes: List[str] = []
+    result = CleaningResult(original=cds, cleaned=seq)
+
+    if enzymes_to_avoid is None:
+        enzymes_to_avoid = ["BsaI"]
+
+    # Step 1: Remove restriction sites via synonymous substitution
+    sites_removed = 0
+    if enzymes_to_avoid and len(seq) >= 3:
+        hits = scan_restriction_sites(seq, enzymes_to_avoid)
+        if hits:
+            codons = [seq[i:i+3] for i in range(0, len(seq) - len(seq) % 3, 3)]
+            for enzyme, site_hits in hits.items():
+                for hit in site_hits:
+                    # Find overlapping codons and try synonymous substitution
+                    codon_idx = hit.position // 3
+                    if 0 <= codon_idx < len(codons):
+                        old_codon = codons[codon_idx]
+                        aa = CODON_TABLE.get(old_codon, "?")
+                        if aa != "?" and aa != "*":
+                            alternatives = [c for c in AA_TO_CODONS[aa] if c != old_codon]
+                            for alt in alternatives:
+                                # Try this substitution and check if site is gone
+                                test_codons = list(codons)
+                                test_codons[codon_idx] = alt
+                                test_seq = "".join(test_codons)
+                                test_hits = scan_restriction_sites(
+                                    test_seq[max(0, hit.position - 6):hit.position + 12],
+                                    [enzyme]
+                                )
+                                if not test_hits:
+                                    codons[codon_idx] = alt
+                                    sites_removed += 1
+                                    changes.append(f"Codon {codon_idx + 1}: {old_codon} → {alt} (removed {enzyme} site)")
+                                    break
+
+            seq = "".join(codons)
+
+    result.restriction_sites_removed = sites_removed
+
+    # Step 2: Replace stop codon with preferred
+    if len(seq) >= 3:
+        last_codon = seq[-3:]
+        if CODON_TABLE.get(last_codon) == "*" and last_codon != preferred_stop:
+            seq = seq[:-3] + preferred_stop
+            changes.append(f"Stop codon: {last_codon} → {preferred_stop}")
+            result.stop_codon_changed = True
+        elif CODON_TABLE.get(last_codon) != "*":
+            seq = seq + preferred_stop
+            changes.append(f"Added stop codon: {preferred_stop}")
+            result.stop_codon_changed = True
+
+    # Step 3: Double stop codon
+    if use_double_stop:
+        second_stop = "TAA" if preferred_stop != "TAA" else "TGA"
+        seq = seq + second_stop
+        changes.append(f"Added second stop codon: {second_stop}")
+        result.double_stop_added = True
+
+    # Step 4: Break homopolymers (simplified - just flag them for demo)
+    if remove_homopolymers:
+        runs = detect_homopolymers(seq, min_run=max_homopolymer + 1)
+        result.homopolymers_shortened = len(runs)
+        if runs:
+            changes.append(f"Flagged {len(runs)} homopolymer run(s) exceeding {max_homopolymer} nt")
+
+    # Step 5: Add adapters
+    if add_5_adapter:
+        seq = add_5_adapter.upper() + seq
+        changes.append(f"Added 5' adapter: {add_5_adapter[:20]}...")
+        result.adapters_added = True
+    if add_3_adapter:
+        seq = seq + add_3_adapter.upper()
+        changes.append(f"Added 3' adapter: {add_3_adapter[:20]}...")
+        result.adapters_added = True
+
+    result.cleaned = seq
+    result.changes = changes
+    return result

core/sequence_tools/codon_optimizer.py

@@ -0,0 +1,155 @@
+"""
+Codon Optimization — optimize CDS codon usage for target organism.
+
+Demo-level implementation that replaces rare codons with frequent ones
+based on the organism's codon usage table.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from core.analysis.cai import CODON_TABLES, calculate_cai
+
+
+# Genetic code
+CODON_TABLE = {
+    "TTT": "F", "TTC": "F", "TTA": "L", "TTG": "L",
+    "CTT": "L", "CTC": "L", "CTA": "L", "CTG": "L",
+    "ATT": "I", "ATC": "I", "ATA": "I", "ATG": "M",
+    "GTT": "V", "GTC": "V", "GTA": "V", "GTG": "V",
+    "TCT": "S", "TCC": "S", "TCA": "S", "TCG": "S",
+    "CCT": "P", "CCC": "P", "CCA": "P", "CCG": "P",
+    "ACT": "T", "ACC": "T", "ACA": "T", "ACG": "T",
+    "GCT": "A", "GCC": "A", "GCA": "A", "GCG": "A",
+    "TAT": "Y", "TAC": "Y", "TAA": "*", "TAG": "*",
+    "CAT": "H", "CAC": "H", "CAA": "Q", "CAG": "Q",
+    "AAT": "N", "AAC": "N", "AAA": "K", "AAG": "K",
+    "GAT": "D", "GAC": "D", "GAA": "E", "GAG": "E",
+    "TGT": "C", "TGC": "C", "TGA": "*", "TGG": "W",
+    "CGT": "R", "CGC": "R", "CGA": "R", "CGG": "R",
+    "AGT": "S", "AGC": "S", "AGA": "R", "AGG": "R",
+    "GGT": "G", "GGC": "G", "GGA": "G", "GGG": "G",
+}
+
+AA_TO_CODONS: Dict[str, List[str]] = {}
+for codon, aa in CODON_TABLE.items():
+    AA_TO_CODONS.setdefault(aa, []).append(codon)
+
+
+@dataclass
+class OptimizationResult:
+    """Result of codon optimization."""
+    original_cds: str
+    optimized_cds: str
+    original_cai: float
+    optimized_cai: float
+    organism: str
+    codons_changed: int
+    total_codons: int
+    changes: List[str] = field(default_factory=list)
+
+
+def optimize_codons(
+    cds: str,
+    organism: str = "human",
+    min_cai_target: float = 0.8,
+    strategy: str = "match_host",
+) -> OptimizationResult:
+    """
+    Optimize codon usage of a CDS for the target organism.
+
+    Parameters
+    ----------
+    cds : str
+        Coding DNA sequence.
+    organism : str
+        Target organism key.
+    min_cai_target : float
+        Target minimum CAI.
+    strategy : str
+        "match_host" — replace rare with frequent.
+        "harmonize" — preserve relative usage.
+        "balance" — avoid most common to prevent tRNA depletion.
+
+    Returns
+    -------
+    OptimizationResult
+    """
+    seq = cds.upper().replace("U", "T")
+    organism_key = organism.lower().replace(" ", "").replace(".", "")
+
+    # Map organism names to table keys
+    org_map = {
+        "human": "human",
+        "mouse": "human",  # similar codon bias
+        "ecoli": "ecoli",
+        "cho": "human",    # similar to human
+        "yeast": "human",  # fallback
+        "zebrafish": "human",
+    }
+    table_key = org_map.get(organism_key, "human")
+    table = CODON_TABLES.get(table_key, CODON_TABLES["human"])
+
+    # Calculate original CAI
+    try:
+        original_cai = calculate_cai(seq, table_key)
+    except Exception:
+        original_cai = 0.0
+
+    # Split into codons
+    codons = [seq[i:i+3] for i in range(0, len(seq) - len(seq) % 3, 3)]
+    optimized = list(codons)
+    changes = []
+    codons_changed = 0
+
+    stop_codons = {"TAA", "TAG", "TGA"}
+
+    for i, codon in enumerate(codons):
+        aa = CODON_TABLE.get(codon, "?")
+        if aa == "?" or aa == "*":
+            continue  # skip unknown and stop codons
+
+        w = table.get(codon, 0.5)
+        if w >= 0.8:
+            continue  # already a good codon
+
+        # Find best alternative codon for this amino acid
+        alternatives = [(c, table.get(c, 0.0)) for c in AA_TO_CODONS.get(aa, []) if c not in stop_codons]
+        if not alternatives:
+            continue
+
+        if strategy == "match_host":
+            # Pick the most frequent codon
+            best = max(alternatives, key=lambda x: x[1])
+        elif strategy == "balance":
+            # Pick a moderately frequent codon (avoid the very top)
+            sorted_alts = sorted(alternatives, key=lambda x: x[1], reverse=True)
+            best = sorted_alts[min(1, len(sorted_alts) - 1)]
+        else:  # harmonize
+            # Keep codons with similar relative frequency
+            best = max(alternatives, key=lambda x: x[1])
+
+        if best[0] != codon and best[1] > w:
+            optimized[i] = best[0]
+            changes.append(f"Pos {i + 1}: {codon} → {best[0]} ({aa}, {w:.2f} → {best[1]:.2f})")
+            codons_changed += 1
+
+    optimized_seq = "".join(optimized)
+
+    # Calculate optimized CAI
+    try:
+        optimized_cai = calculate_cai(optimized_seq, table_key)
+    except Exception:
+        optimized_cai = 0.0
+
+    return OptimizationResult(
+        original_cds=cds,
+        optimized_cds=optimized_seq,
+        original_cai=original_cai,
+        optimized_cai=optimized_cai,
+        organism=organism,
+        codons_changed=codons_changed,
+        total_codons=len(codons),
+        changes=changes,
+    )

demo/README.md

@@ -0,0 +1,87 @@
+# mRNA Design Studio — Demo Database
+
+This directory contains demo databases for testing the import functionality.
+
+## PostgreSQL Demo (Recommended)
+
+A containerized PostgreSQL database with realistic mRNA sequence data.
+
+### Start the Database
+
+```bash
+cd demo
+docker-compose up -d
+```
+
+Wait a few seconds for the database to initialize, then verify it's running:
+
+```bash
+docker-compose ps
+```
+
+### Connection Details
+
+- **Host**: `localhost`
+- **Port**: `5432`
+- **Database**: `mrna_studio`
+- **User**: `demo_user`
+- **Password**: `demo_pass_2024`
+
+### Connect in the App
+
+1. Open the app at http://localhost:5007
+2. Click **"⊕  Import Database"** in the sidebar
+3. Select **"PostgreSQL"** as backend
+4. Enter the connection details above
+5. Click **Connect**
+6. Select the `mrna_sequences` table
+7. Click **Preview** to see the data
+8. Map columns (auto-suggestions should work)
+9. Click **Import Records**
+
+### Stop the Database
+
+```bash
+cd demo
+docker-compose down
+```
+
+To remove all data:
+
+```bash
+docker-compose down -v
+```
+
+---
+
+## SQLite Demo (Simple Alternative)
+
+A local file-based database. No server required.
+
+### Create the Database
+
+```bash
+python demo/create_demo_db.py
+```
+
+### Connection Details
+
+- **Backend**: SQLite
+- **File Path**: `/Users/nicholasjustice/repos/mrna_design_studio/demo/mrna_parts.db`
+
+---
+
+## Demo Data Contents
+
+### mrna_sequences Table (4 records)
+
+1. **eGFP-hBG-UTRs** - Component-based (separate 5'UTR, CDS, 3'UTR, poly-A)
+2. **mCherry-AlbUTR** - Component-based with Albumin 3'UTR
+3. **eGFP-full-v2** - Monolithic (entire mRNA in `full_mrna` field)
+4. **mCherry-full** - Monolithic with EMCV IRES
+
+The mix demonstrates how SchemaMapper handles different database schemas.
+
+### plasmid_backbones Table (1 record)
+
+1. **pUC19-MCS** - Classic E. coli cloning vector

demo/cds_only_sequences.csv

@@ -0,0 +1,5 @@
+gene_name,cds,target_protein,organism,expression_system,notes
+eGFP,ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA,Enhanced GFP,Aequorea victoria,HEK293T,CDS only — no UTRs. Good for codon optimization testing.
+mCherry,ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA,mCherry RFP,Discosoma sp.,CHO,CDS only — red fluorescent protein for codon usage analysis.
+Firefly_Luciferase,ATGGAAGACGCCAAAAACATAAAGAAAGGCCCGGCGCCATTCTATCCGCTGGAAGATGGAACCGCTGGAGAGCAACTGCATAAGGCTATGAAGAGATACGCCCTGGTTCCTGGAACAATTGCTTTTACAGATGCACATATCGAGGTGGACATCACTTACGCTGAGTACTTCGAAATGTCCGTTCGGTTGGCAGAAGCTATGAAACGATATGGGCTGAATACAAATCACAGAATCGTCGTATGCAGTGAAAACTCTCTTCAATTCTTTATGCCGGTGTTGGGCGCGTTATTTATCGGAGTTGCAGTTGCGCCCGCGAACGACATTTATAATGAACGTGAATTGCTCAACAGTATGGGCATTTCGCAGCCTACCGTGGTGTTCGTTTCCAAAAAGGGGTTGCAAAAAATTTTGAACGTGCAAAAAAAGCTCCCAATCATCCAAAAAATTATTATCATGGATTCTAAAACGGATTACCAGGGATTTCAGTCGATGTACACGTTCGTCACATCTCATCTACCTCCCGGTTTTAATGAATACGATTTTGTGCCAGAGTCCTTCGATAGGGACAAGACAATTGCACTGATCATGAACTCCTCTGGATCTACTGGTCTGCCTAAAGGTGTCGCTCTGCCTCATAGAACTGCCTGCGTGAGATTCTCGCATGCCAGAGATCCTATTTTTGGCAATCAAATCATTCCGGATACTGCGATTTTAAGTGTTGTTCCATTCCATCACGGTTTTGGAATGTTTACTACACTCGGATATTTGATATGTGGATTTCGAGTCGTCTTAATGTATAGATTTGAAGAAGAGCTGTTTCTGAGGAGCCTTCAGGATTACAAGATTCAAAGTGCGCTGCTGGTGCCAACCCTATTCTCCTTCTTCGCCAAAAGCACTCTGATTGACAAATACGATTTATCTAATTTACACGAAATTGCTTCTGGTGGCGCTCCCCTCTCTAAGGAAGTCGGGGAAGCGGTTGCCAAGAGGTTCCATCTGCCAGGTATCAGGCAAGGATATGGGCTCACTGAGACTACATCAGCTATTCTGATTACACCCGAGGGGGATGATAAACCGGGCGCGGTCGGTAAAGTTGTTCCATTTTTTGAAGCGAAGGTTGTGGATCTGGATACCGGGAAAACGCTGGGCGTTAATCAAAGAGGCGAACTGTGTGTGAGAGGTCCTATGATTATGTCCGGTTATGTAAACAATCCGGAAGCGACCAACGCCTTGATTGACAAGGATGGATGGCTACATTCTGGAGACATAGCTTACTGGGACGAAGACGAACACTTCTTCATCGTTGACCGCCTGAAGTCTCTGATTAAGTACAAAGGCTATCAGGTGGCTCCCGCTGAATTGGAATCCATCTTGCTCCAACACCCCAACATCTTCGACGCAGGTGTCGCAGGTCTTCCCGACGATGACGCCGGTGAACTTCCCGCCGCCGTTGTTGTTTTGGAGCACGGAAAGACGATGACGGAAAAAGAGATCGTGGATTACGTCGCCAGTCAAGTAACAACCGCGAAAAAGTTGCGCGGAGGAGTTGTGTTTGTGGACGAAGTACCGAAAGGTCTTACCGGAAAACTCGACGCAAGAAAAATCAGAGAGATCCTCATAAAGGCCAAGAAGGGCGGAAAGATCGCCGTGTAA,Firefly Luciferase,Photinus pyralis,E. coli,CDS only — bioluminescence reporter for prokaryotic expression.
+hEPO,ATGGGCGTGCACGAATGTCCTGCCTGGCTGTGGCTTCTCCTGTCCCTGCTGTCGCTCCCTCTGGGCCTCCCAGTCCTGGGCGCCCCACCACGCCTCATCTGTGACAGCCGAGTCCTGGAGAGGTACCTCTTGGAGGCCAAGGAGGCCGAGAATATCACGACGGGCTGTGCTGAACACTGCAGCTTGAATGAGAATATCACTGTCCCAGACACCAAAGTTAATTTCTATGCCTGGAAGAGGATGGAGGTCGGGCAGCAGGCCGTAGAAGTCTGGCAGGGCCTGGCCCTGCTGTCGGAAGCTGTCCTGCGGGGCCAGGCCCTGTTGGTCAACTCTTCCCAGCCGTGGGAGCCCCTGCAGCTGCATGTGGATAAAGCCGTCAGTGGCCTTCGCAGCCTCACCACTCTGCTTCGGGCTCTGGGAGCCCAGAAGGAAGCCATCTCCCCTCCAGATGCGGCCTCAGCTGCTCCACTCCGAACAATCACTGCTGACACTTTCCGCAAACTCTTCCGAGTCTACTCCAATTTCCTCCGGGGAAAGCTGAAGCTGTACACAGGGGAGGCCTGCAGGACAGGGGACAGATGA,Human Erythropoietin,Homo sapiens,CHO,CDS only — therapeutic protein for codon optimization.

demo/create_csv.py

@@ -0,0 +1,179 @@
+"""
+Create CSV version of the demo database for easy import testing.
+"""
+import csv
+import os
+
+# Same sequences as in create_demo_db.py
+UTR5_BETAGLOBIN = (
+    "ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGAC"
+    "TCCTGAGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGGTGAACGTGGATGAAGTTGGTGGT"
+)[:80]
+
+UTR5_EMCV = "GGGAAATAAGAGAGAAAAGAAGAGTAAGAAGAAATATAAGAGCCACCATG"
+KOZAK_TEV = "GCCACC"
+
+UTR3_BETAGLOBIN = (
+    "GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTA"
+    "AACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGATTCTGCCTAATAAAAAACATTTATT"
+    "TTCATTGCAATGATGTATTTAAATTATTTCTGAATATTTTACTAAAAATAAATGTTTTTTAT"
+)[:100]
+
+UTR3_ALBUMIN = (
+    "AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTA"
+    "AATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGAGGCAGAGCCATCTATTGCTTACAT"
+)[:100]
+
+POLYA_120 = "A" * 120
+POLYA_60 = "A" * 60
+
+CDS_EGFP = (
+    "ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAG"
+    "TAA"
+)
+
+CDS_MCHERRY = (
+    "ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAG"
+    "TAA"
+)
+
+CDS_LUC2 = (
+    "ATGGAAGATGCCAAAAACATTAAGAAGGGCCCAGCGCCATTCTACCCACTCGAAGACGGGAC"
+    "CGCCGGCGAGCAGCTGCACAAAGCCATGAAGCGCTACGCCCTGGTGCCCGGCACCATCGCCT"
+    "TTACCGACGCACATATCGAGGTGGACATTACCTACGCCGAGTACTTCGAGATGAGCGTTCGG"
+    "CTGGCAGAAGCTATGAAGCGCTATGGGCTGAATACAAACCATCGGATCGTGGTGTGCAGCGA"
+    "GAATAGTCTGGAGAAGATCCTGCTGAACAAAGGCCTGCCTGTAGCCGGCCTTTTCCTCCTGG"
+    "AAGAGCTGCGGCAGCAGTTCCAGAAGGCCCGGGAGCAGATGTTCACCTTCGTGCTCGATCTG"
+    "GAGGAAATGACCGCCGAAGAGGCGATTGAGAATCTGGTATTCGAGCAGTATGGAATCGACCA"
+    "TTATCTTGATAACCCACAATGCCTGCATGACCTGGTGCATCTGGAACCCCGAGGTCAATGTG"
+    "GAAGAGTTCCTGGAAAAGCTGCTGAAGGACGGTATCATCATGTTCAGCATCCATGGTTATGG"
+    "CTACATCCTGGGGCCCGGAACCAACTTCGATCTGGAGCGCATGATCAAGCGCGATGGGGAG"
+    "GTGGATATGGCCCTGATTAAGGTGTCGATGGAGCAGGCCGGCATCGACCCCGATGAGGCCGG"
+    "AGCCATTCGGCTGTACAAGCTGATGAAGGATAAG"
+    "TAA"
+)[:900]
+while len(CDS_LUC2) % 3 != 0:
+    CDS_LUC2 = CDS_LUC2[:-3] + "TAA"
+
+CDS_SPIKE_RBD = (
+    "ATGTTCGTGTTCCTGGTGCTGCTGCCCCTGGTGTCCTCCCAGGTGTGCAACCTGACCACCAG"
+    "AACCCAGCTGCCCCCCGCCTACACCAACTCCTTCACCCGGGGCGTGTACTACCCCGACAAGG"
+    "TGTTCCGCTCCTCCGTGCTGCACTCCACCCAGGACCTGTTTCTGCCCTTTTTCTCCAACGTG"
+    "ACCTGGTTCCACGCCATCCACGTGTCCGGCACCAACGGCACAAAGCGGTTCGACAACCCCGTG"
+    "CTGCCCTTCAACGACGGGGTGTACTTTGCCAGCACCGAGAAGTCCAACATCATCCGGGGCTG"
+    "GATCTTCGGCACCACCCTGGACTCCAAGACCCAGTCCCTGCTGATCGTGAACAACGCCACCA"
+    "ACGTGGTCATCAAGGTGTGCGAGTTCCAGTTCTGCAACGACCCCTTCCTGGGCGTCTACTAC"
+    "CACAAGAACAACAAGTCCTGGATGGAGTCCGAGTTCCGGGTGTACTCCTCCGCCAACAACTG"
+    "CACCTTTGAGTACGTGTCCCAGCCCTTTCTGATGGACCTGGAGGGCAAACAGGGCAACTTCA"
+    "AGAACCTGCGCGAGTTTGTGTTTAAGAACATCGACGGCTACTTCAAGATCTACAGCAAGCAC"
+)
+CDS_SPIKE_RBD = CDS_SPIKE_RBD[:len(CDS_SPIKE_RBD) - len(CDS_SPIKE_RBD) % 3]
+CDS_SPIKE_RBD = CDS_SPIKE_RBD[:-3] + "TAA"
+
+CDS_EPO = (
+    "ATGGGGGTGCACGAATGTCCCGCCTGGCTGTGGCTGCTGCTGTCGCTGCCGTTCTCTGTGCT"
+    "GCCCGCCCGCGCCGTCCTCACCGTCAACTTCCCGCACCCTGCTTCCACGCCTCAGAGTCCTG"
+    "GAGAGGTACCTCTTGGAGGCCAAGGAGGCCGAGAATATCACGACGGGCTGTGCTGAACACTGC"
+    "AGCTTGAATGAGAATATCACGGTGCGCTTTCCACGCCTCATTTGCGACAGCTTTGTTCGTGG"
+    "TCAGGCCGTGGTCAGCTCCGATGAGGTCTTCAGGGCCCCTGTCCTCCTGCAGCTGGAATCCT"
+    "GGCAGCGTCTCAGCCCCTGCAGCCAGCCCTCCCAGCTGCCCTCAGCCACCTGTCCCGCCTGCT"
+    "CCAGAGCCTGGAGAACTTCTACCAGCCTCTGGAGCAGCTCCAGGAAGTGATCCAGGAGATGAG"
+    "CAAGCTGTCCGCCACGGCCGTGGAGGTCTTGGCCAGTAAGCCGGAG"
+    "TAA"
+)
+CDS_EPO = CDS_EPO[:len(CDS_EPO) - len(CDS_EPO) % 3]
+if not CDS_EPO.endswith("TAA") and not CDS_EPO.endswith("TAG") and not CDS_EPO.endswith("TGA"):
+    CDS_EPO = CDS_EPO[:-3] + "TAA"
+
+CDS_FIX = (
+    "ATGCAGCGCGTGAACATGATCATGGCCTCCCTGTGGCTGTGCTTCGTGGCCCTGTGGCAGGC"
+    "TGGCAACCCCAGAGAAGTACCTGTTCAAGAACGGCGACCAGCGGCCCAACAAGGAGATCCCCA"
+    "AGAGCATCATCCTGGAGGAGTTCAAGGCCTTCTTCTCCACCTTCATCAACCGGAAGATGATCA"
+    "AGCAGACCGACAAAGACCAGGTGATCAGCCTGGGCGGCAAGGACCAGGTGCTGATCCAGATGC"
+    "AGCCCCAGGTGAGCAAGGACTTTGGCTTCAGCCTGTGCACCTGCCCCTGGGGCCACCCCAGCC"
+    "CCTGCAGCAGCACATCCTGTACTTCCTGAACCAGAAGGCCAAACAGTTCCTGCTGCAGGACGAG"
+    "AAGGTGAAGGGCATCAACCACTGCAAGGTGCGGGTGGCCCTGGAGCAGGACGGCAGCAAGGTG"
+)
+CDS_FIX = CDS_FIX[:len(CDS_FIX) - len(CDS_FIX) % 3]
+CDS_FIX = CDS_FIX[:-3] + "TAA"
+
+FULL_MRNA_EGFP = UTR5_BETAGLOBIN + KOZAK_TEV + "ATG" + CDS_EGFP[3:] + UTR3_BETAGLOBIN + POLYA_120
+FULL_MRNA_MCHERRY = UTR5_EMCV + CDS_MCHERRY + UTR3_ALBUMIN + POLYA_60
+
+# Build CSV rows
+CSV_DATA = [
+    {
+        'id': 1,
+        'gene_name': 'eGFP-hBG-UTRs',
+        'five_prime_utr': UTR5_BETAGLOBIN,
+        'cds': CDS_EGFP,
+        'three_prime_utr': UTR3_BETAGLOBIN,
+        'poly_a_tail': POLYA_120,
+        'full_mrna': '',
+        'target_protein': 'Enhanced GFP',
+        'organism': 'Aequorea victoria',
+        'expression_system': 'HEK293T',
+        'gc_target_percent': 52.4,
+        'notes': 'Human beta-globin UTRs. Classic reporter construct for mRNA transfection.'
+    },
+    {
+        'id': 2,
+        'gene_name': 'mCherry-AlbUTR',
+        'five_prime_utr': UTR5_BETAGLOBIN,
+        'cds': CDS_MCHERRY,
+        'three_prime_utr': UTR3_ALBUMIN,
+        'poly_a_tail': POLYA_120,
+        'full_mrna': '',
+        'target_protein': 'mCherry red fluorescent protein',
+        'organism': 'Discosoma sp.',
+        'expression_system': 'CHO',
+        'gc_target_percent': 50.1,
+        'notes': 'Albumin 3\'UTR for extended expression. Good cell viability.'
+    },
+    {
+        'id': 3,
+        'gene_name': 'Luc2-reporter',
+        'five_prime_utr': UTR5_EMCV,
+        'cds': CDS_LUC2,
+        'three_prime_utr': UTR3_ALBUMIN,
+        'poly_a_tail': POLYA_60,
+        'full_mrna': '',
+        'target_protein': 'Firefly luciferase',
+        'organism': 'Photinus pyralis',
+        'expression_system': 'Huh-7',
+        'gc_target_percent': 53.8,
+        'notes': 'Bioluminescence reporter. Used for LNP screening.'
+    },
+    {
+        'id': 4,
+        'gene_name': 'SpRBD-v1',
+        'five_prime_utr': UTR5_BETAGLOBIN,
+        'cds': CDS_SPIKE_RBD,
+        'three_prime_utr': UTR3_ALBUMIN,
+        'poly_a_tail': POLYA_120,
+        'full_mrna': '',
+        'target_protein': 'SARS-CoV-2 Spike RBD',
+        'organism': 'SARS-CoV-2',
+        'expression_system': 'HEK293T',
+        'gc_target_percent': 55.2,
+        'notes': 'Vaccine antigen candidate. Proline-stabilized RBD.'
+    },
+]
+
+def create_csv():
+    output_path = os.path.join(os.path.dirname(__file__), 'mrna_sequences.csv')
+
+    with open(output_path, 'w', newline='') as f:
+        fieldnames = ['id', 'gene_name', 'five_prime_utr', 'cds', 'three_prime_utr',
+                      'poly_a_tail', 'full_mrna', 'target_protein', 'organism',
+                      'expression_system', 'gc_target_percent', 'notes']
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(CSV_DATA)
+
+    print(f'✓ Created {output_path}')
+    print(f'  {len(CSV_DATA)} sequences exported')
+    return output_path
+
+if __name__ == '__main__':
+    create_csv()

demo/create_demo_db.py

@@ -0,0 +1,260 @@
+"""
+Creates the demo SQLite database: demo/mrna_parts.db
+
+Tables
+------
+mrna_sequences  — main parts registry (mix of full mRNA and component records)
+plasmid_backbones — a few cloning vectors
+
+Run:  python demo/create_demo_db.py
+"""
+import sqlite3
+import os
+
+DB_PATH = os.path.join(os.path.dirname(__file__), "mrna_parts.db")
+
+# ── Sequences are realistic-length DNA (T not U), all valid reading frames ──
+
+# Human beta-globin 5'UTR (commonly used in mRNA therapeutics)
+UTR5_BETAGLOBIN = (
+    "ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGAC"
+    "TCCTGAGGAGAAGTCTGCCGTTACTGCCCTGTGGGGCAAGGTGAACGTGGATGAAGTTGGTGGT"
+)[:80]
+
+# EMCV IRES-derived 5'UTR (used in bicistronic vectors)
+UTR5_EMCV = (
+    "GGGAAATAAGAGAGAAAAGAAGAGTAAGAAGAAATATAAGAGCCACCATG"
+)
+
+# Tobacco etch virus (TEV) minimal Kozak context
+KOZAK_TEV  = "GCCACC"
+
+# Human beta-globin 3'UTR
+UTR3_BETAGLOBIN = (
+    "GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTA"
+    "AACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGATTCTGCCTAATAAAAAACATTTATT"
+    "TTCATTGCAATGATGTATTTAAATTATTTCTGAATATTTTACTAAAAATAAATGTTTTTTAT"
+)[:100]
+
+# Human albumin 3'UTR (strong, widely used)
+UTR3_ALBUMIN = (
+    "AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTA"
+    "AATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGAGGCAGAGCCATCTATTGCTTACAT"
+)[:100]
+
+# Poly-A tail
+POLYA_120 = "A" * 120
+POLYA_60  = "A" * 60
+
+# ── CDS sequences — all start ATG, end stop codon, in-frame ──────────────────
+
+# eGFP (enhanced Green Fluorescent Protein) — 720 nt human-codon-optimized
+CDS_EGFP = (
+    "ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAG"
+    "TAA"  # stop codon
+)
+
+# mCherry CDS — 711 nt, codon-optimized for human
+CDS_MCHERRY = (
+    "ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAG"
+    "TAA"
+)
+
+# Firefly luciferase — human codon-optimized excerpt (900 nt out of full ~1650)
+CDS_LUC2 = (
+    "ATGGAAGATGCCAAAAACATTAAGAAGGGCCCAGCGCCATTCTACCCACTCGAAGACGGGAC"
+    "CGCCGGCGAGCAGCTGCACAAAGCCATGAAGCGCTACGCCCTGGTGCCCGGCACCATCGCCT"
+    "TTACCGACGCACATATCGAGGTGGACATTACCTACGCCGAGTACTTCGAGATGAGCGTTCGG"
+    "CTGGCAGAAGCTATGAAGCGCTATGGGCTGAATACAAACCATCGGATCGTGGTGTGCAGCGA"
+    "GAATAGTCTGGAGAAGATCCTGCTGAACAAAGGCCTGCCTGTAGCCGGCCTTTTCCTCCTGG"
+    "AAGAGCTGCGGCAGCAGTTCCAGAAGGCCCGGGAGCAGATGTTCACCTTCGTGCTCGATCTG"
+    "GAGGAAATGACCGCCGAAGAGGCGATTGAGAATCTGGTATTCGAGCAGTATGGAATCGACCA"
+    "TTATCTTGATAACCCACAATGCCTGCATGACCTGGTGCATCTGGAACCCCGAGGTCAATGTG"
+    "GAAGAGTTCCTGGAAAAGCTGCTGAAGGACGGTATCATCATGTTCAGCATCCATGGTTATGG"
+    "CTACATCCTGGGGCCCGGAACCAACTTCGATCTGGAGCGCATGATCAAGCGCGATGGGGAG"
+    "GTGGATATGGCCCTGATTAAGGTGTCGATGGAGCAGGCCGGCATCGACCCCGATGAGGCCGG"
+    "AGCCATTCGGCTGTACAAGCTGATGAAGGATAAG"
+    "TAA"
+)[:900]
+# Pad to make divisible by 3
+while len(CDS_LUC2) % 3 != 0:
+    CDS_LUC2 = CDS_LUC2[:-3] + "TAA"
+
+# Truncated Spike RBD (SARS-CoV-2) — synthetic, codon-optimized excerpt
+CDS_SPIKE_RBD = (
+    "ATGTTCGTGTTCCTGGTGCTGCTGCCCCTGGTGTCCTCCCAGGTGTGCAACCTGACCACCAG"
+    "AACCCAGCTGCCCCCCGCCTACACCAACTCCTTCACCCGGGGCGTGTACTACCCCGACAAGG"
+    "TGTTCCGCTCCTCCGTGCTGCACTCCACCCAGGACCTGTTTCTGCCCTTTTTCTCCAACGTG"
+    "ACCTGGTTCCACGCCATCCACGTGTCCGGCACCAACGGCACAAAGCGGTTCGACAACCCCGTG"
+    "CTGCCCTTCAACGACGGGGTGTACTTTGCCAGCACCGAGAAGTCCAACATCATCCGGGGCTG"
+    "GATCTTCGGCACCACCCTGGACTCCAAGACCCAGTCCCTGCTGATCGTGAACAACGCCACCA"
+    "ACGTGGTCATCAAGGTGTGCGAGTTCCAGTTCTGCAACGACCCCTTCCTGGGCGTCTACTAC"
+    "CACAAGAACAACAAGTCCTGGATGGAGTCCGAGTTCCGGGTGTACTCCTCCGCCAACAACTG"
+    "CACCTTTGAGTACGTGTCCCAGCCCTTTCTGATGGACCTGGAGGGCAAACAGGGCAACTTCA"
+    "AGAACCTGCGCGAGTTTGTGTTTAAGAACATCGACGGCTACTTCAAGATCTACAGCAAGCAC"
+)
+# Ensure divisible by 3 with stop codon
+CDS_SPIKE_RBD = CDS_SPIKE_RBD[:len(CDS_SPIKE_RBD) - len(CDS_SPIKE_RBD) % 3]
+CDS_SPIKE_RBD = CDS_SPIKE_RBD[:-3] + "TAA"  # replace last codon with stop
+
+# EPO (Erythropoietin) CDS — synthetic excerpt
+CDS_EPO = (
+    "ATGGGGGTGCACGAATGTCCCGCCTGGCTGTGGCTGCTGCTGTCGCTGCCGTTCTCTGTGCT"
+    "GCCCGCCCGCGCCGTCCTCACCGTCAACTTCCCGCACCCTGCTTCCACGCCTCAGAGTCCTG"
+    "GAGAGGTACCTCTTGGAGGCCAAGGAGGCCGAGAATATCACGACGGGCTGTGCTGAACACTGC"
+    "AGCTTGAATGAGAATATCACGGTGCGCTTTCCACGCCTCATTTGCGACAGCTTTGTTCGTGG"
+    "TCAGGCCGTGGTCAGCTCCGATGAGGTCTTCAGGGCCCCTGTCCTCCTGCAGCTGGAATCCT"
+    "GGCAGCGTCTCAGCCCCTGCAGCCAGCCCTCCCAGCTGCCCTCAGCCACCTGTCCCGCCTGCT"
+    "CCAGAGCCTGGAGAACTTCTACCAGCCTCTGGAGCAGCTCCAGGAAGTGATCCAGGAGATGAG"
+    "CAAGCTGTCCGCCACGGCCGTGGAGGTCTTGGCCAGTAAGCCGGAG"
+    "TAA"
+)
+# Truncate to multiples of 3
+CDS_EPO = CDS_EPO[:len(CDS_EPO) - len(CDS_EPO) % 3]
+if not CDS_EPO.endswith("TAA") and not CDS_EPO.endswith("TAG") and not CDS_EPO.endswith("TGA"):
+    CDS_EPO = CDS_EPO[:-3] + "TAA"
+
+# hFIX (Factor IX) — synthetic
+CDS_FIX = (
+    "ATGCAGCGCGTGAACATGATCATGGCCTCCCTGTGGCTGTGCTTCGTGGCCCTGTGGCAGGC"
+    "TGGCAACCCCAGAGAAGTACCTGTTCAAGAACGGCGACCAGCGGCCCAACAAGGAGATCCCCA"
+    "AGAGCATCATCCTGGAGGAGTTCAAGGCCTTCTTCTCCACCTTCATCAACCGGAAGATGATCA"
+    "AGCAGACCGACAAAGACCAGGTGATCAGCCTGGGCGGCAAGGACCAGGTGCTGATCCAGATGC"
+    "AGCCCCAGGTGAGCAAGGACTTTGGCTTCAGCCTGTGCACCTGCCCCTGGGGCCACCCCAGCC"
+    "CCTGCAGCAGCACATCCTGTACTTCCTGAACCAGAAGGCCAAACAGTTCCTGCTGCAGGACGAG"
+    "AAGGTGAAGGGCATCAACCACTGCAAGGTGCGGGTGGCCCTGGAGCAGGACGGCAGCAAGGTG"
+)
+CDS_FIX = CDS_FIX[:len(CDS_FIX) - len(CDS_FIX) % 3]
+CDS_FIX = CDS_FIX[:-3] + "TAA"
+
+# ── Full mRNA sequences (some customers store it monolithic) ──────────────────
+
+FULL_MRNA_EGFP = UTR5_BETAGLOBIN + KOZAK_TEV + "ATG" + CDS_EGFP[3:] + UTR3_BETAGLOBIN + POLYA_120
+FULL_MRNA_MCHERRY = UTR5_EMCV + CDS_MCHERRY + UTR3_ALBUMIN + POLYA_60
+
+# ── Sequences table data ───────────────────────────────────────────────────────
+
+SEQUENCES = [
+    # id, gene_name, five_prime_utr, cds, three_prime_utr, poly_a_tail,
+    # target_protein, organism, expression_system, gc_target, notes
+    (1, "eGFP-hBG-UTRs", UTR5_BETAGLOBIN, CDS_EGFP, UTR3_BETAGLOBIN, POLYA_120,
+     "Enhanced GFP", "Aequorea victoria", "HEK293T", 52.4,
+     "Human beta-globin UTRs. Classic reporter construct for mRNA transfection."),
+
+    (2, "mCherry-AlbUTR", UTR5_BETAGLOBIN, CDS_MCHERRY, UTR3_ALBUMIN, POLYA_120,
+     "mCherry red fluorescent protein", "Discosoma sp.", "CHO", 50.1,
+     "Albumin 3'UTR for extended expression. Good cell viability."),
+
+    (3, "Luc2-reporter", UTR5_EMCV, CDS_LUC2, UTR3_ALBUMIN, POLYA_60,
+     "Firefly luciferase", "Photinus pyralis", "Huh-7", 53.8,
+     "Bioluminescence reporter. Used for LNP screening."),
+
+    (4, "SpRBD-v1", UTR5_BETAGLOBIN, CDS_SPIKE_RBD, UTR3_ALBUMIN, POLYA_120,
+     "SARS-CoV-2 Spike RBD", "SARS-CoV-2", "HEK293T", 55.2,
+     "Vaccine antigen candidate. Proline-stabilized RBD."),
+
+    (5, "EPO-therapeutic", UTR5_BETAGLOBIN, CDS_EPO, UTR3_BETAGLOBIN, POLYA_120,
+     "Erythropoietin", "Homo sapiens", "HepG2", 58.0,
+     "Therapeutic candidate for anemia. Glycosylation motifs retained."),
+
+    (6, "hFIX-codon-opt", UTR5_BETAGLOBIN, CDS_FIX, UTR3_ALBUMIN, POLYA_120,
+     "Coagulation Factor IX", "Homo sapiens", "HepG2", 56.3,
+     "Hemophilia B gene therapy candidate. Codon-optimized for liver expression."),
+
+    # Records stored as full_mrna (no component breakdown) — different schema
+    (7, "eGFP-full-v2", None, None, None, None,
+     "eGFP monolithic record", "Aequorea victoria", "in vitro", 51.9,
+     "Archive record — stored as assembled mRNA sequence."),
+
+    (8, "mCherry-EMCV-full", None, None, None, None,
+     "mCherry EMCV", "Discosoma sp.", "Jurkat", 49.7,
+     "EMCV IRES-driven construct. Full sequence stored."),
+]
+
+# full_mrna is only for rows 7 and 8
+FULL_MRNA = {
+    7: FULL_MRNA_EGFP,
+    8: FULL_MRNA_MCHERRY,
+}
+
+# ── Plasmid backbones ─────────────────────────────────────────────────────────
+
+# pUC19 minimal cloning region (stub — real pUC19 is 2686 bp)
+BACKBONE_PUC19 = "ATGACCATGATTACGCCAAGCTTGCATGCCTGCAGGTCGACGGATCCCCGGGAATTCGAGCTC" + "GCTAGC" * 40
+BACKBONE_CMV = "GGTACCGAGCTCGAATTCGTAATCATGGTCATAGCTGTTTCCTGTGTGAAATTGTTATCCGCT" + "AAGCTT" * 40
+
+BACKBONES = [
+    (1, "pUC19-MCS", BACKBONE_PUC19,
+     "EcoRI,HindIII,BamHI,SalI,PstI,SphI",
+     "Classic E. coli cloning vector. AmpR. lacZ alpha complementation."),
+
+    (2, "pCMV-MCS", BACKBONE_CMV,
+     "EcoRI,HindIII,XhoI,NheI,NotI",
+     "Mammalian expression vector. CMV promoter. BGH poly-A signal."),
+]
+
+# ── Build the database ─────────────────────────────────────────────────────────
+
+def create() -> None:
+    if os.path.exists(DB_PATH):
+        os.remove(DB_PATH)
+
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+
+    c.execute("""
+        CREATE TABLE mrna_sequences (
+            id                INTEGER PRIMARY KEY,
+            gene_name         TEXT    NOT NULL,
+            five_prime_utr    TEXT,
+            cds               TEXT,
+            three_prime_utr   TEXT,
+            poly_a_tail       TEXT,
+            full_mrna         TEXT,
+            target_protein    TEXT,
+            organism          TEXT,
+            expression_system TEXT,
+            gc_target_percent REAL,
+            notes             TEXT
+        )
+    """)
+
+    for row in SEQUENCES:
+        (rid, name, utr5, cds, utr3, polya,
+         protein, organism, expsys, gc, notes) = row
+        full = FULL_MRNA.get(rid)
+        c.execute("""
+            INSERT INTO mrna_sequences VALUES (?,?,?,?,?,?,?,?,?,?,?,?)
+        """, (rid, name, utr5, cds, utr3, polya, full,
+              protein, organism, expsys, gc, notes))
+
+    c.execute("""
+        CREATE TABLE plasmid_backbones (
+            id           INTEGER PRIMARY KEY,
+            name         TEXT,
+            sequence     TEXT,
+            cloning_sites TEXT,
+            description  TEXT
+        )
+    """)
+
+    for row in BACKBONES:
+        c.execute("INSERT INTO plasmid_backbones VALUES (?,?,?,?,?)", row)
+
+    conn.commit()
+    conn.close()
+
+    print(f"✓ Created demo database: {DB_PATH}")
+    print(f"  mrna_sequences : {len(SEQUENCES)} records")
+    print(f"  plasmid_backbones: {len(BACKBONES)} records")
+
+    # Quick validation
+    conn2 = sqlite3.connect(DB_PATH)
+    count = conn2.execute("SELECT COUNT(*) FROM mrna_sequences").fetchone()[0]
+    conn2.close()
+    assert count == len(SEQUENCES), "Row count mismatch!"
+    print("  ✓ Validation passed")
+
+
+if __name__ == "__main__":
+    create()

demo/demo_models.py

@@ -0,0 +1,166 @@
+"""
+Demo script for mRNA scoring models.
+
+Shows how to use the RNAstructure MFE and mRNA Stability scorers.
+"""
+from core.models.sequence import mRNASequence
+from models import RNAStructureMFEScorer, mRNAStabilityScorer, ModelRegistry
+
+
+def demo_individual_scorers():
+    """Demo individual model scoring."""
+    print("=" * 60)
+    print("Demo: Individual Model Scoring")
+    print("=" * 60)
+
+    # Create a test mRNA sequence
+    seq = mRNASequence(
+        name="EGFP_construct",
+        source="local",
+        five_prime_utr="GTTGCTCCTTCGGGCCTGTGGCGGCT",
+        kozak="GCCACCATGG",
+        cds="ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAG",
+        three_prime_utr="TGCCTGCTGCCGAGCGCCTGCGCGCGCGCGAG",
+        poly_a="AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+    )
+
+    print(f"\nSequence: {seq.name}")
+    print(f"Length: {seq.length} nt")
+    print(f"Components: 5'UTR, Kozak, CDS, 3'UTR, PolyA\n")
+
+    # Score with RNAstructure MFE
+    print("-" * 60)
+    print("RNAstructure MFE Scorer")
+    print("-" * 60)
+    mfe_scorer = RNAStructureMFEScorer()
+    mfe_score = mfe_scorer.score(seq)
+    print(f"Score: {mfe_score:.1f}/100")
+    print(f"Interpretation: ", end="")
+    if mfe_score < 40:
+        print("Weak secondary structure")
+    elif mfe_score < 70:
+        print("Optimal structure for translation ✓")
+    else:
+        print("Strong structure (may inhibit translation)")
+
+    # Score with mRNA Stability
+    print("\n" + "-" * 60)
+    print("mRNA Stability Scorer")
+    print("-" * 60)
+    stability_scorer = mRNAStabilityScorer(organism="human")
+    stability_score = stability_scorer.score(seq)
+    print(f"Overall Score: {stability_score:.1f}/100")
+    print(f"Interpretation: ", end="")
+    if stability_score >= 70:
+        print("Excellent design ✓")
+    elif stability_score >= 40:
+        print("Acceptable design")
+    else:
+        print("Poor design, optimization recommended")
+
+    # Show component scores
+    print("\n  Component Breakdown:")
+    gc_score = stability_scorer._score_gc_content(seq)
+    cai_score = stability_scorer._score_cai(seq)
+    homopoly_score = stability_scorer._score_homopolymers(seq)
+    utr_score = stability_scorer._score_utr_structure(seq)
+    kozak_score = stability_scorer._score_kozak(seq)
+
+    if gc_score is not None:
+        print(f"    GC Content (30%):   {gc_score:.1f}/100")
+    if cai_score is not None:
+        print(f"    CAI (25%):          {cai_score:.1f}/100")
+    if homopoly_score is not None:
+        print(f"    Homopolymers (20%): {homopoly_score:.1f}/100")
+    if utr_score is not None:
+        print(f"    5' UTR (15%):       {utr_score:.1f}/100")
+    if kozak_score is not None:
+        print(f"    Kozak (10%):        {kozak_score:.1f}/100")
+
+
+def demo_model_registry():
+    """Demo ModelRegistry integration."""
+    print("\n\n" + "=" * 60)
+    print("Demo: ModelRegistry Integration")
+    print("=" * 60)
+
+    # Create sequences
+    sequences = [
+        mRNASequence(
+            name="seq_good",
+            source="local",
+            five_prime_utr="GTTGCTCCTTCGGGCCTGTGGCGGCT",
+            kozak="GCCACCATGG",
+            cds="ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGG" * 2,
+        ),
+        mRNASequence(
+            name="seq_poor",
+            source="local",
+            cds="ATGAAAAAAAAAAAAAAAAAAAAAAATGA",  # Poor: homopolymers, low GC
+        ),
+        mRNASequence(
+            name="seq_medium",
+            source="local",
+            five_prime_utr="ACGTACGT",
+            cds="ATGCGACGATCGATCGATCGACGATGA",
+        ),
+    ]
+
+    # Create registry
+    registry = ModelRegistry()
+
+    # Register models
+    registry._register(RNAStructureMFEScorer(), "scoring", "builtin", "")
+    registry._register(mRNAStabilityScorer(), "scoring", "builtin", "")
+
+    print(f"\nRegistered models: {len(registry.scoring_models)}")
+    for model in registry.scoring_models:
+        print(f"  - {model.model.name}")
+
+    # Score all sequences with both models
+    print("\n" + "-" * 60)
+    print("Scoring Results")
+    print("-" * 60)
+
+    for model_reg in registry.scoring_models:
+        model_name = model_reg.model.name
+        print(f"\n{model_name}:")
+        results = registry.run_scoring(model_name, sequences)
+        for _, row in results.iterrows():
+            print(f"  {row['name']:15} → {row['score']:5.1f}")
+
+
+def demo_batch_scoring():
+    """Demo batch scoring efficiency."""
+    print("\n\n" + "=" * 60)
+    print("Demo: Batch Scoring")
+    print("=" * 60)
+
+    # Create 10 test sequences
+    sequences = [
+        mRNASequence(
+            name=f"seq_{i:02d}",
+            source="local",
+            cds="ATGCGATCGATCGATCG" * (i + 1),
+        )
+        for i in range(10)
+    ]
+
+    scorer = mRNAStabilityScorer()
+
+    # Batch score
+    scores = scorer.score_batch(sequences)
+
+    print(f"\nScored {len(sequences)} sequences:")
+    for seq, score in zip(sequences, scores):
+        print(f"  {seq.name}: {score:.1f}/100 ({seq.length} nt)")
+
+
+if __name__ == "__main__":
+    demo_individual_scorers()
+    demo_model_registry()
+    demo_batch_scoring()
+
+    print("\n" + "=" * 60)
+    print("Demo Complete!")
+    print("=" * 60)

demo/docker-compose.yml

@@ -0,0 +1,19 @@
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: mrna_studio_demo_db
+    environment:
+      POSTGRES_DB: mrna_studio
+      POSTGRES_USER: demo_user
+      POSTGRES_PASSWORD: demo_pass_2024
+    ports:
+      - "5432:5432"
+    volumes:
+      - ./init_postgres.sql:/docker-entrypoint-initdb.d/init.sql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U demo_user -d mrna_studio"]
+      interval: 5s
+      timeout: 5s
+      retries: 5

demo/init_postgres.sql

@@ -0,0 +1,89 @@
+-- mRNA Design Studio Demo Database
+-- PostgreSQL initialization script
+
+-- Create sequences table
+CREATE TABLE mrna_sequences (
+    id                SERIAL PRIMARY KEY,
+    gene_name         VARCHAR(255) NOT NULL,
+    five_prime_utr    TEXT,
+    cds               TEXT,
+    three_prime_utr   TEXT,
+    poly_a_tail       TEXT,
+    full_mrna         TEXT,
+    target_protein    VARCHAR(255),
+    organism          VARCHAR(255),
+    expression_system VARCHAR(255),
+    gc_target_percent DECIMAL(5,2),
+    notes             TEXT,
+    created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Insert demo sequences
+INSERT INTO mrna_sequences (gene_name, five_prime_utr, cds, three_prime_utr, poly_a_tail, full_mrna, target_protein, organism, expression_system, gc_target_percent, notes) VALUES
+('eGFP-hBG-UTRs',
+ 'ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAG',
+ 'ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA',
+ 'GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGA',
+ 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+ NULL,
+ 'Enhanced GFP',
+ 'Aequorea victoria',
+ 'HEK293T',
+ 52.4,
+ 'Human beta-globin UTRs. Classic reporter construct for mRNA transfection.'),
+
+('mCherry-AlbUTR',
+ 'ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAG',
+ 'ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA',
+ 'AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCA',
+ 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+ NULL,
+ 'mCherry red fluorescent protein',
+ 'Discosoma sp.',
+ 'CHO',
+ 50.1,
+ 'Albumin 3''UTR for extended expression. Good cell viability.'),
+
+('eGFP-full-v2',
+ NULL, NULL, NULL, NULL,
+ 'ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGGCCACCATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAGCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+ 'eGFP monolithic record',
+ 'Aequorea victoria',
+ 'in vitro',
+ 51.9,
+ 'Archive record — stored as assembled mRNA sequence.'),
+
+('mCherry-full',
+ NULL, NULL, NULL, NULL,
+ 'GGGAAATAAGAGAGAAAAGAAGAGTAAGAAGAAATATAAGAGCCACCATGATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAAAATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+ 'mCherry EMCV',
+ 'Discosoma sp.',
+ 'Jurkat',
+ 49.7,
+ 'EMCV IRES-driven construct. Full sequence stored.');
+
+-- Create plasmid backbones table
+CREATE TABLE plasmid_backbones (
+    id            SERIAL PRIMARY KEY,
+    name          VARCHAR(255) NOT NULL,
+    sequence      TEXT NOT NULL,
+    cloning_sites TEXT,
+    description   TEXT,
+    created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Insert demo plasmid backbones
+INSERT INTO plasmid_backbones (name, sequence, cloning_sites, description) VALUES
+('pUC19-MCS',
+ 'ATGACCATGATTACGCCAAGCTTGCATGCCTGCAGGTCGACGGATCCCCGGGAATTCGAGCTCGCTAGCGCTAGCGCTAGCGCTAGCGCTAGCGCTAGC',
+ 'EcoRI,HindIII,BamHI,SalI,PstI',
+ 'Classic E. coli cloning vector. AmpR. lacZ alpha complementation.');
+
+-- Create indexes for better query performance
+CREATE INDEX idx_mrna_gene_name ON mrna_sequences(gene_name);
+CREATE INDEX idx_mrna_organism ON mrna_sequences(organism);
+CREATE INDEX idx_plasmid_name ON plasmid_backbones(name);
+
+-- Grant permissions
+GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO demo_user;
+GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO demo_user;

demo/init_railway_db.py

@@ -0,0 +1,73 @@
+"""
+Initialize the Railway PostgreSQL database with demo tables and data.
+
+Reads connection details from environment variables (PGHOST, PGPORT, etc.)
+or accepts a DATABASE_URL.
+
+Usage:
+    python demo/init_railway_db.py
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from sqlalchemy import create_engine, text
+
+
+def get_database_url() -> str:
+    """Build a PostgreSQL URL from environment variables."""
+    url = os.environ.get("DATABASE_URL", "").strip()
+    if url:
+        return url
+
+    host = os.environ.get("PGHOST", "localhost")
+    port = os.environ.get("PGPORT", "5432")
+    db = os.environ.get("PGDATABASE", "railway")
+    user = os.environ.get("PGUSER", "postgres")
+    pw = os.environ.get("PGPASSWORD", "")
+    return f"postgresql+psycopg2://{user}:{pw}@{host}:{port}/{db}"
+
+
+def main() -> None:
+    url = get_database_url()
+    safe_url = url.split("@")[-1] if "@" in url else url
+    print(f"Connecting to: ...@{safe_url}")
+
+    engine = create_engine(url)
+
+    sql_path = os.path.join(os.path.dirname(__file__), "init_postgres.sql")
+    with open(sql_path) as f:
+        sql = f.read()
+
+    # Remove the GRANT lines (Railway uses postgres user, not demo_user)
+    lines = [
+        line for line in sql.splitlines()
+        if not line.strip().startswith("GRANT ")
+    ]
+    sql_clean = "\n".join(lines)
+
+    with engine.begin() as conn:
+        # Drop existing tables first (safe re-run)
+        conn.execute(text("DROP TABLE IF EXISTS mrna_sequences CASCADE"))
+        conn.execute(text("DROP TABLE IF EXISTS plasmid_backbones CASCADE"))
+        print("Dropped existing tables (if any)")
+
+        # Execute each statement
+        for statement in sql_clean.split(";"):
+            stmt = statement.strip()
+            if stmt and not stmt.startswith("--"):
+                conn.execute(text(stmt))
+
+    # Verify
+    with engine.connect() as conn:
+        seq_count = conn.execute(text("SELECT COUNT(*) FROM mrna_sequences")).scalar()
+        bb_count = conn.execute(text("SELECT COUNT(*) FROM plasmid_backbones")).scalar()
+
+    print(f"Done! Created:")
+    print(f"  mrna_sequences:   {seq_count} rows")
+    print(f"  plasmid_backbones: {bb_count} rows")
+
+
+if __name__ == "__main__":
+    main()

demo/mrna_sequences.csv

@@ -0,0 +1,3 @@
+id,gene_name,five_prime_utr,cds,three_prime_utr,poly_a_tail,full_mrna,target_protein,organism,expression_system,gc_target_percent,notes
+1,eGFP-hBG-UTRs,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCT,ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA,GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGAT,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,Enhanced GFP,Aequorea victoria,HEK293T,52.4,Human beta-globin UTRs. Classic reporter construct for mRNA transfection.
+2,mCherry-AlbUTR,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCT,ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA,AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGA,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,mCherry red fluorescent protein,Discosoma sp.,CHO,50.1,Albumin 3'UTR for extended expression. Good cell viability.

demo/utr_library.csv

@@ -0,0 +1,7 @@
+gene_name,five_prime_utr,three_prime_utr,utr5_name,utr3_name,organism,notes
+hBG-UTRs,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCT,GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGAT,Human beta-globin 5'UTR,Human beta-globin 3'UTR,Homo sapiens,Classic mRNA therapeutic UTRs from BNT162b2. High translation efficiency in human cells.
+Albumin-UTRs,AGATCTTCTTTTAAATTTCTTTTTACTGAATTCAGCCAATATATGTAATCCTACTTTCAATCAATTTTCCTAAGCAATG,AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGA,Human albumin 5'UTR,Human albumin 3'UTR,Homo sapiens,Albumin UTRs for extended expression and mRNA stability.
+Alpha-globin-UTRs,ACTCTTCTGGTCCCCACAGACTCAGAGAGAACCCACCATG,GCTGGAGCCTCGGTGGCCATGCTTCTTGCCCCTTGGGCCTCCCCCCAGCCCCTCCTCCCCTTCCTGCACCCGTACCCCCGTGGTCTTTGAATAAAGTCTGA,Human alpha-globin 5'UTR,Human alpha-globin 3'UTR,Homo sapiens,Alpha-globin UTRs. Commonly used in mRNA vaccine designs (Moderna mRNA-1273).
+TEV-leader,AATTAAAATTTTATTTTTTTTTTTTGGAATATAAATG,,TEV 5' leader sequence,,Tobacco etch virus,TEV leader for cap-independent translation. Often used with viral IRES elements.
+HCV-IRES,CCTGTGAGGAACTACTGTCTTCACGCAGAAAGCGTCTAGCCATGGCGTTAGTATGAGTGTCGTGCAGCCTCCAGGACCCCCCCTCCCGGGAGAGCCATAGTGGTCTGCGGAACCGGTGAGTACACCGGAATTGCCAGGACGACCGGGTCCTTTCTTGGATCAACCCGCTCAATGCCTGGAGATTTGGGCGTGCCCCCGCGAGACTGCTAGCCGAGTAGTGTTGGGTCGCGAAAGGCCTTGTGGTACTGCCTGATAGGGTGCTTGCGAGTGCCCCGGGAGGTCTCGTAGACCGTGCACCATG,,HCV IRES 5'UTR,,Hepatitis C virus,Full HCV IRES for cap-independent translation initiation.
+Xenopus-bGlobin,GCTTGTTCTTTTTGCAGAAGCTCAGAATAAACGCTCAACTTTGGCAGATCG,TGTCACCATGGTCTTTCTTCTTTCTCTCCTCTTTTCTTTTTAATTAATAAAAAATGGAAAGAACCTCAGAAC,Xenopus beta-globin 5'UTR,Xenopus beta-globin 3'UTR,Xenopus laevis,Widely used in IVT mRNA research. Standard reference UTR pair.

models/README.md

@@ -0,0 +1,162 @@
+# mRNA Scoring Models
+
+This directory contains built-in mRNA scoring models for the mRNA Design Studio.
+
+## Available Models
+
+### 1. RNAstructure MFE Scorer (`rna_structure_scorer.py`)
+
+**Purpose**: Predicts the minimum free energy (MFE) of mRNA secondary structure.
+
+**Method**: Uses ViennaRNA RNAfold algorithm to compute the thermodynamic stability of RNA secondary structures. More negative MFE values indicate stronger secondary structure formation.
+
+**Score Range**: 0-100
+- **0-40**: Weak/unstable secondary structure (may be too unstructured)
+- **40-70**: Moderate secondary structure (**optimal range** for translation)
+- **70-100**: Strong secondary structure (may inhibit translation)
+
+**Dependencies**:
+- ViennaRNA Python package (optional)
+- If ViennaRNA is not available, falls back to GC-content based proxy scoring
+
+**Usage**:
+```python
+from models import RNAStructureMFEScorer
+
+scorer = RNAStructureMFEScorer()
+score = scorer.score(sequence)
+```
+
+**Interpretation**:
+- Target moderate scores (40-70) for optimal translation efficiency
+- Very low scores suggest the mRNA may be prone to degradation
+- Very high scores suggest strong secondary structures that may block ribosome access
+
+---
+
+### 2. mRNA Stability Scorer (`mrna_stability_scorer.py`)
+
+**Purpose**: Composite stability prediction based on multiple sequence features.
+
+**Method**: Combines five established mRNA design principles:
+1. **GC Content** (30% weight) - Optimal: 50-60%
+2. **Codon Adaptation Index (CAI)** (25% weight) - Codon optimization for host organism
+3. **Homopolymer Detection** (20% weight) - Penalizes long runs of identical nucleotides
+4. **5' UTR Structure** (15% weight) - Moderate stability preferred
+5. **Kozak Consensus** (10% weight) - Translation initiation efficiency
+
+**Score Range**: 0-100
+- **0-40**: Poor stability/translation efficiency
+- **40-70**: Acceptable design
+- **70-100**: Excellent design
+
+**Dependencies**:
+- BioPython (optional, for advanced CAI calculation)
+- ViennaRNA (optional, for UTR structure analysis)
+
+**Parameters**:
+- `organism` (default: "human") - Target organism for codon optimization
+
+**Usage**:
+```python
+from models import mRNAStabilityScorer
+
+scorer = mRNAStabilityScorer(organism="human")
+score = scorer.score(sequence)
+```
+
+**Individual Component Scores**:
+
+You can access individual component scores for detailed analysis:
+```python
+scorer = mRNAStabilityScorer()
+
+# Individual component scores
+gc_score = scorer._score_gc_content(sequence)      # 0-100
+cai_score = scorer._score_cai(sequence)           # 0-100
+homopoly_score = scorer._score_homopolymers(sequence)  # 0-100
+utr_score = scorer._score_utr_structure(sequence) # 0-100
+kozak_score = scorer._score_kozak(sequence)       # 0-100
+```
+
+**Interpretation**:
+- **70+**: Well-designed mRNA suitable for production
+- **40-70**: Moderate quality, may benefit from optimization
+- **<40**: Significant design issues, optimization strongly recommended
+
+---
+
+## Model Registry Integration
+
+Both models implement the `ScoringModel` interface and can be loaded into the ModelRegistry:
+
+```python
+from models import ModelRegistry, RNAStructureMFEScorer, mRNAStabilityScorer
+
+registry = ModelRegistry()
+
+# Register built-in models
+registry._register(RNAStructureMFEScorer(), "scoring", "builtin", "models/rna_structure_scorer.py")
+registry._register(mRNAStabilityScorer(), "scoring", "builtin", "models/mrna_stability_scorer.py")
+
+# Run scoring on sequences
+import pandas as pd
+results = registry.run_scoring("RNAstructure MFE", sequences)
+```
+
+---
+
+## Testing
+
+Run tests for both models:
+```bash
+pytest tests/test_models.py::TestRNAStructureMFEScorer -v
+pytest tests/test_models.py::TestmRNAStabilityScorer -v
+```
+
+---
+
+## Adding Custom Models
+
+To add your own scoring model:
+
+1. Create a new Python file in this directory
+2. Import and subclass `ScoringModel`:
+
+```python
+from models.base import ScoringModel
+from core.models.sequence import mRNASequence
+
+class MyCustomScorer(ScoringModel):
+    @property
+    def name(self) -> str:
+        return "My Custom Scorer"
+
+    @property
+    def description(self) -> str:
+        return "Description of what this model does"
+
+    def score(self, sequence: mRNASequence, metadata=None) -> float:
+        # Your scoring logic here
+        return 0.0  # Return score 0-100
+```
+
+3. Load it via the ModelRegistry:
+
+```python
+models = registry.load_local("path/to/your_model.py")
+```
+
+---
+
+## References
+
+### RNAstructure MFE Scorer
+- Lorenz et al. (2011). "ViennaRNA Package 2.0." *Algorithms for Molecular Biology*, 6:26.
+- Turner & Mathews (2010). "NNDB: the nearest neighbor parameter database for predicting stability of nucleic acid secondary structure." *Nucleic Acids Research*, 38:D280-282.
+
+### mRNA Stability Scorer
+- Mauro & Edelman (2002). "The ribosome filter hypothesis." *PNAS*, 99(19):12031-12036. (Kozak sequence)
+- Sharp & Li (1987). "The codon adaptation index—a measure of directional synonymous codon usage bias." *Nucleic Acids Research*, 15(3):1281-1295.
+- Kudla et al. (2009). "Coding-sequence determinants of gene expression in Escherichia coli." *Science*, 324(5924):255-258.
+- Presnyak et al. (2015). "Codon optimality is a major determinant of mRNA stability." *Cell*, 160(6):1111-1124.

models/__init__.py

@@ -0,0 +1,32 @@
+"""
+Model plugin system for mRNA Design Studio.
+
+Included models:
+- RNAStructureMFEScorer: Secondary structure MFE prediction
+- mRNAStabilityScorer: Composite stability prediction based on multiple factors
+"""
+
+from models.base import (
+    ScoringModel,
+    GenerativeModel,
+    ModelRegistry,
+    APIScoringModel,
+    APIGenerativeModel,
+    RegisteredModel,
+)
+
+from models.rna_structure_scorer import RNAStructureMFEScorer
+from models.mrna_stability_scorer import mRNAStabilityScorer
+
+__all__ = [
+    # Base classes
+    "ScoringModel",
+    "GenerativeModel",
+    "ModelRegistry",
+    "APIScoringModel",
+    "APIGenerativeModel",
+    "RegisteredModel",
+    # Concrete models
+    "RNAStructureMFEScorer",
+    "mRNAStabilityScorer",
+]

models/base.py

@@ -0,0 +1,447 @@
+"""
+Model plugin system.
+
+Users can contribute two types of models:
+
+1. ScoringModel  — scores an existing mRNASequence, returns a float.
+2. GenerativeModel — generates new mRNASequences from constraints / seeds.
+
+Models are loaded via ModelRegistry which supports:
+  - Local Python module (path on disk or importable package)
+  - Remote REST API endpoint (POST sequences → scores/generations)
+
+The API adapter wraps HTTP calls behind the same interface so the UI
+code never needs to know whether a model is local or remote.
+"""
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import sys
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Type, Union
+
+import pandas as pd
+
+from core.models.sequence import mRNASequence
+
+
+# ── Abstract base classes ────────────────────────────────────────────────────
+
+class ScoringModel(ABC):
+    """
+    A model that assigns a numeric score to an mRNASequence.
+
+    Implement name and score(). scores_batch() has a default list
+    implementation but can be overridden for vectorised inference.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable model name shown in the UI."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Optional description for the UI."""
+        return ""
+
+    @property
+    def version(self) -> str:
+        return "1.0"
+
+    @abstractmethod
+    def score(self, sequence: mRNASequence, metadata: Optional[Dict[str, Any]] = None) -> float:
+        """
+        Score a single sequence.
+
+        Parameters
+        ----------
+        sequence : mRNASequence
+        metadata : dict, optional
+            Raw database metadata attached to the sequence (raw_metadata).
+
+        Returns
+        -------
+        float
+            Score value. Convention: higher is better, but models may
+            define their own scale — document it in description.
+        """
+        ...
+
+    def score_batch(
+        self,
+        sequences: List[mRNASequence],
+        metadata: Optional[List[Optional[Dict[str, Any]]]] = None,
+    ) -> List[float]:
+        """Score a list of sequences. Override for vectorised models."""
+        metas = metadata or [None] * len(sequences)
+        return [self.score(seq, meta) for seq, meta in zip(sequences, metas)]
+
+
+class GenerativeModel(ABC):
+    """
+    A model that generates new mRNASequences from constraints or seed sequences.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        ...
+
+    @property
+    def description(self) -> str:
+        return ""
+
+    @property
+    def version(self) -> str:
+        return "1.0"
+
+    @abstractmethod
+    def generate(
+        self,
+        constraints: Dict[str, Any],
+        n: int = 10,
+        seed: Optional[mRNASequence] = None,
+    ) -> List[mRNASequence]:
+        """
+        Generate n sequences from the given constraints.
+
+        Parameters
+        ----------
+        constraints : dict
+            Model-specific constraint dict (e.g. target GC, CAI, organism, etc.)
+        n : int
+            Number of sequences to generate.
+        seed : mRNASequence, optional
+            Seed sequence for mutation-based generators.
+
+        Returns
+        -------
+        List[mRNASequence]
+        """
+        ...
+
+
+ModelType = Union[ScoringModel, GenerativeModel]
+
+
+# ── API Adapter ──────────────────────────────────────────────────────────────
+
+class APIScoringModel(ScoringModel):
+    """
+    Wraps a remote REST API behind the ScoringModel interface.
+
+    Expected API contract:
+      POST {endpoint}/score
+      Body: {"sequences": [{"id": ..., "sequence": ...}, ...]}
+      Response: {"scores": [{"id": ..., "score": float}, ...]}
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        model_name: str,
+        api_key: Optional[str] = None,
+        description: str = "",
+        version: str = "1.0",
+        timeout: float = 30.0,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._name = model_name
+        self._api_key = api_key
+        self._description = description
+        self._version = version
+        self._timeout = timeout
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def version(self) -> str:
+        return self._version
+
+    def _headers(self) -> Dict[str, str]:
+        h = {"Content-Type": "application/json"}
+        if self._api_key:
+            h["Authorization"] = f"Bearer {self._api_key}"
+        return h
+
+    def score(self, sequence: mRNASequence, metadata: Optional[Dict[str, Any]] = None) -> float:
+        results = self.score_batch([sequence], [metadata])
+        return results[0]
+
+    def score_batch(
+        self,
+        sequences: List[mRNASequence],
+        metadata: Optional[List[Optional[Dict[str, Any]]]] = None,
+    ) -> List[float]:
+        import httpx
+
+        payload = {
+            "sequences": [
+                {
+                    "id": seq.id,
+                    "name": seq.name,
+                    "sequence": seq.assembled_sequence,
+                    "metadata": (metadata[i] if metadata else None),
+                }
+                for i, seq in enumerate(sequences)
+            ]
+        }
+        response = httpx.post(
+            f"{self._endpoint}/score",
+            json=payload,
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+        score_map = {item["id"]: item["score"] for item in data["scores"]}
+        return [score_map.get(seq.id, float("nan")) for seq in sequences]
+
+
+class APIGenerativeModel(GenerativeModel):
+    """
+    Wraps a remote REST API behind the GenerativeModel interface.
+
+    Expected API contract:
+      POST {endpoint}/generate
+      Body: {"constraints": {...}, "n": int, "seed_sequence": str | null}
+      Response: {"sequences": [{"name": ..., "cds": ..., ...}, ...]}
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        model_name: str,
+        api_key: Optional[str] = None,
+        description: str = "",
+        version: str = "1.0",
+        timeout: float = 60.0,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._name = model_name
+        self._api_key = api_key
+        self._description = description
+        self._version = version
+        self._timeout = timeout
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def version(self) -> str:
+        return self._version
+
+    def _headers(self) -> Dict[str, str]:
+        h = {"Content-Type": "application/json"}
+        if self._api_key:
+            h["Authorization"] = f"Bearer {self._api_key}"
+        return h
+
+    def generate(
+        self,
+        constraints: Dict[str, Any],
+        n: int = 10,
+        seed: Optional[mRNASequence] = None,
+    ) -> List[mRNASequence]:
+        import httpx
+
+        payload = {
+            "constraints": constraints,
+            "n": n,
+            "seed_sequence": seed.assembled_sequence if seed else None,
+        }
+        response = httpx.post(
+            f"{self._endpoint}/generate",
+            json=payload,
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return [mRNASequence.from_dict({**item, "source": "local"}) for item in data["sequences"]]
+
+
+# ── Model Registry ───────────────────────────────────────────────────────────
+
+@dataclass
+class RegisteredModel:
+    model: ModelType
+    model_type: str       # "scoring" | "generative"
+    source: str           # "local" | "api" | "builtin" | "catalog"
+    source_path: str = "" # file path or endpoint URL
+    repository: str = ""  # display provenance (e.g. "github.com/ViennaRNA")
+    category: str = ""    # model category for display
+
+
+class ModelRegistry:
+    """
+    Manages loaded scoring and generative models.
+
+    Models are registered either by loading a local Python file/module
+    or by configuring an API endpoint.
+    """
+
+    def __init__(self) -> None:
+        self._models: Dict[str, RegisteredModel] = {}
+
+    # ── Loading ──────────────────────────────────────────────────────────────
+
+    def load_local(self, path: str) -> List[ModelType]:
+        """
+        Dynamically import a Python file and register all ScoringModel /
+        GenerativeModel subclasses found in it.
+
+        Returns the list of loaded model instances.
+        """
+        spec = importlib.util.spec_from_file_location("_user_model", path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load module from: {path}")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+
+        loaded: List[ModelType] = []
+        for _, obj in inspect.getmembers(module, inspect.isclass):
+            if obj.__module__ != module.__name__:
+                continue
+            if issubclass(obj, ScoringModel) and obj is not ScoringModel:
+                instance = obj()
+                self._register(instance, "scoring", "local", path)
+                loaded.append(instance)
+            elif issubclass(obj, GenerativeModel) and obj is not GenerativeModel:
+                instance = obj()
+                self._register(instance, "generative", "local", path)
+                loaded.append(instance)
+
+        if not loaded:
+            raise ValueError(
+                f"No ScoringModel or GenerativeModel subclasses found in {path}."
+            )
+        return loaded
+
+    def register_api_scorer(
+        self,
+        endpoint: str,
+        model_name: str,
+        api_key: Optional[str] = None,
+        description: str = "",
+    ) -> APIScoringModel:
+        """Register a remote scoring API."""
+        model = APIScoringModel(
+            endpoint=endpoint,
+            model_name=model_name,
+            api_key=api_key,
+            description=description,
+        )
+        self._register(model, "scoring", "api", endpoint)
+        return model
+
+    def register_api_generator(
+        self,
+        endpoint: str,
+        model_name: str,
+        api_key: Optional[str] = None,
+        description: str = "",
+    ) -> APIGenerativeModel:
+        """Register a remote generative API."""
+        model = APIGenerativeModel(
+            endpoint=endpoint,
+            model_name=model_name,
+            api_key=api_key,
+            description=description,
+        )
+        self._register(model, "generative", "api", endpoint)
+        return model
+
+    # ── Running ──────────────────────────────────────────────────────────────
+
+    def run_scoring(
+        self,
+        model_name: str,
+        sequences: List[mRNASequence],
+    ) -> pd.DataFrame:
+        """
+        Run a scoring model against sequences and return a DataFrame.
+
+        Columns: id, name, score
+        """
+        reg = self._get(model_name, "scoring")
+        scorer: ScoringModel = reg.model  # type: ignore[assignment]
+        scores = scorer.score_batch(sequences)
+        return pd.DataFrame({
+            "id": [s.id for s in sequences],
+            "name": [s.name for s in sequences],
+            "score": scores,
+        })
+
+    def run_generation(
+        self,
+        model_name: str,
+        constraints: Dict[str, Any],
+        n: int = 10,
+        seed: Optional[mRNASequence] = None,
+    ) -> List[mRNASequence]:
+        """Run a generative model and return new sequences."""
+        reg = self._get(model_name, "generative")
+        generator: GenerativeModel = reg.model  # type: ignore[assignment]
+        return generator.generate(constraints, n=n, seed=seed)
+
+    # ── Query ────────────────────────────────────────────────────────────────
+
+    @property
+    def scoring_models(self) -> List[RegisteredModel]:
+        return [r for r in self._models.values() if r.model_type == "scoring"]
+
+    @property
+    def generative_models(self) -> List[RegisteredModel]:
+        return [r for r in self._models.values() if r.model_type == "generative"]
+
+    @property
+    def all_models(self) -> List[RegisteredModel]:
+        return list(self._models.values())
+
+    def unregister(self, model_name: str) -> bool:
+        if model_name in self._models:
+            del self._models[model_name]
+            return True
+        return False
+
+    # ── Internal ─────────────────────────────────────────────────────────────
+
+    def _register(
+        self,
+        model: ModelType,
+        model_type: str,
+        source: str,
+        source_path: str,
+    ) -> None:
+        self._models[model.name] = RegisteredModel(
+            model=model,
+            model_type=model_type,
+            source=source,
+            source_path=source_path,
+        )
+
+    def _get(self, name: str, expected_type: str) -> RegisteredModel:
+        if name not in self._models:
+            raise KeyError(f"Model '{name}' not found in registry.")
+        reg = self._models[name]
+        if reg.model_type != expected_type:
+            raise TypeError(
+                f"Model '{name}' is a {reg.model_type} model, not {expected_type}."
+            )
+        return reg

models/catalog.py

@@ -0,0 +1,314 @@
+"""
+Curated catalog of public mRNA models for the Model Repository browser.
+
+Each entry represents a real publicly available model/tool. The catalog
+is hardcoded for demo purposes — in production this would be fetched
+from a model registry API.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass
+class ModelCatalogEntry:
+    """A model available for import from the catalog."""
+    name: str
+    model_type: str          # "analytical" | "generative"
+    category: str            # "Structure", "Stability", "Codon Optimization", etc.
+    description: str
+    repository: str          # e.g. "github.com/ViennaRNA/ViennaRNA"
+    repository_url: str
+    deployment: str          # "embedded" | "api" | "both"
+    version: str
+    paper: str               # citation
+    paper_url: str
+    icon: str                # emoji
+    tags: List[str] = field(default_factory=list)
+    inputs: str = ""         # "Full mRNA sequence", "CDS only", etc.
+    status: str = "available"  # "available" | "imported" | "connected"
+
+
+def get_model_catalog() -> List[ModelCatalogEntry]:
+    """Return the curated model catalog."""
+    catalog: List[ModelCatalogEntry] = []
+
+    # ── Analytical Models ────────────────────────────────────────────────────
+
+    catalog.append(ModelCatalogEntry(
+        name="ViennaRNA (RNAfold)",
+        model_type="analytical",
+        category="Structure Prediction",
+        description="Gold-standard thermodynamic RNA secondary structure prediction. Computes MFE structures, partition functions, and base-pair probabilities.",
+        repository="github.com/ViennaRNA/ViennaRNA",
+        repository_url="https://github.com/ViennaRNA/ViennaRNA",
+        deployment="embedded",
+        version="2.6.4",
+        paper="Lorenz et al., ViennaRNA Package 2.0, Algorithms Mol Biol (2011)",
+        paper_url="https://doi.org/10.1186/1748-7188-6-26",
+        icon="🧬",
+        tags=["scoring", "MFE", "secondary structure", "thermodynamics"],
+        inputs="Full mRNA sequence",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="LinearFold",
+        model_type="analytical",
+        category="Structure Prediction",
+        description="Linear-time RNA secondary structure prediction using beam search. Orders of magnitude faster than cubic-time algorithms on long sequences.",
+        repository="github.com/LinearFold/LinearFold",
+        repository_url="https://github.com/LinearFold/LinearFold",
+        deployment="embedded",
+        version="1.0",
+        paper="Huang et al., LinearFold: linear-time approximate RNA folding, Bioinformatics (2019)",
+        paper_url="https://doi.org/10.1093/bioinformatics/btz375",
+        icon="⚡",
+        tags=["scoring", "MFE", "secondary structure", "fast"],
+        inputs="Full mRNA sequence",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="EternaFold",
+        model_type="analytical",
+        category="Structure Prediction",
+        description="RNA secondary structure prediction trained on Eterna player data. Improved accuracy on structured RNA elements.",
+        repository="github.com/eternagame/EternaFold",
+        repository_url="https://github.com/eternagame/EternaFold",
+        deployment="embedded",
+        version="1.3",
+        paper="Wayment-Steele et al., RNA secondary structure packages evaluated, Nat Methods (2022)",
+        paper_url="https://doi.org/10.1038/s41592-022-01605-0",
+        icon="🎯",
+        tags=["scoring", "secondary structure", "deep learning"],
+        inputs="Full mRNA sequence",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="Optimus 5-Prime",
+        model_type="analytical",
+        category="UTR Scoring",
+        description="Predicts mean ribosome load from 5' UTR sequence. Convolutional model trained on massively parallel reporter assays.",
+        repository="github.com/pjsample/human_5utr_modeling",
+        repository_url="https://github.com/pjsample/human_5utr_modeling",
+        deployment="embedded",
+        version="1.0",
+        paper="Sample et al., Human 5' UTR design and variant effect prediction, Nat Biotechnol (2019)",
+        paper_url="https://doi.org/10.1038/s41587-019-0164-5",
+        icon="📊",
+        tags=["scoring", "UTR", "translation", "ribosome load"],
+        inputs="5' UTR only",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="RNAdegformer",
+        model_type="analytical",
+        category="Stability / Degradation",
+        description="Transformer model predicting per-nucleotide RNA degradation rates. Trained on OpenVaccine challenge data.",
+        repository="github.com/Shujun-He/RNAdegformer",
+        repository_url="https://github.com/Shujun-He/RNAdegformer",
+        deployment="embedded",
+        version="1.0",
+        paper="He et al., RNAdegformer, competition solution (2020)",
+        paper_url="https://arxiv.org/abs/2110.07531",
+        icon="📉",
+        tags=["scoring", "stability", "degradation", "transformer"],
+        inputs="Full mRNA sequence",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="Saluki",
+        model_type="analytical",
+        category="Stability / Half-life",
+        description="Deep learning model predicting mRNA half-life from sequence and structure. Integrates codon usage, UTR features, and secondary structure.",
+        repository="github.com/vagarwal87/saluki_paper",
+        repository_url="https://github.com/vagarwal87/saluki_paper",
+        deployment="embedded",
+        version="1.0",
+        paper="Agarwal & Kelley, The genetic and biochemical determinants of mRNA degradation rates, Genome Biol (2022)",
+        paper_url="https://doi.org/10.1186/s13059-022-02811-x",
+        icon="⏱️",
+        tags=["scoring", "half-life", "stability", "deep learning"],
+        inputs="Full mRNA sequence",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="CodonFM (NVIDIA)",
+        model_type="analytical",
+        category="Foundation Model",
+        description="Foundation model for codon-level mRNA representations. Pre-trained on millions of coding sequences for downstream tasks.",
+        repository="github.com/NVIDIA-Digital-Bio/CodonFM",
+        repository_url="https://github.com/NVIDIA-Digital-Bio/CodonFM",
+        deployment="both",
+        version="1.0",
+        paper="NVIDIA Digital Biology, CodonFM (2024)",
+        paper_url="https://github.com/NVIDIA-Digital-Bio/CodonFM",
+        icon="🏗️",
+        tags=["foundation model", "embeddings", "codon", "NVIDIA"],
+        inputs="CDS only",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="mRNABERT",
+        model_type="analytical",
+        category="Foundation Model",
+        description="BERT-based foundation model for mRNA sequences. Generates contextual embeddings useful for property prediction and design.",
+        repository="huggingface.co/YYLY66/mRNABERT",
+        repository_url="https://huggingface.co/YYLY66/mRNABERT",
+        deployment="embedded",
+        version="1.0",
+        paper="Yang et al., mRNABERT (2023)",
+        paper_url="https://huggingface.co/YYLY66/mRNABERT",
+        icon="🤖",
+        tags=["foundation model", "BERT", "embeddings", "HuggingFace"],
+        inputs="Full mRNA sequence",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="Riboformer",
+        model_type="analytical",
+        category="Translation Efficiency",
+        description="Transformer model predicting translation efficiency from mRNA sequence. Models ribosome dynamics and codon-level features.",
+        repository="Paper",
+        repository_url="https://doi.org/10.1101/2023.09.09.556981",
+        deployment="embedded",
+        version="1.0",
+        paper="Gu et al., Riboformer: a deep learning framework for predicting context-dependent translation dynamics (2023)",
+        paper_url="https://doi.org/10.1101/2023.09.09.556981",
+        icon="🔬",
+        tags=["scoring", "translation", "ribosome", "transformer"],
+        inputs="Full mRNA sequence",
+    ))
+
+    # ── Generative Models ────────────────────────────────────────────────────
+
+    catalog.append(ModelCatalogEntry(
+        name="GEMORNA",
+        model_type="generative",
+        category="Full mRNA Design",
+        description="Generative model for complete mRNA sequence design. Jointly optimizes codon usage, UTR selection, and structural stability.",
+        repository="github.com/RainaBio/GEMORNA",
+        repository_url="https://github.com/RainaBio/GEMORNA",
+        deployment="embedded",
+        version="1.0",
+        paper="Raina Bio, GEMORNA (2024)",
+        paper_url="https://github.com/RainaBio/GEMORNA",
+        icon="🧪",
+        tags=["generative", "full mRNA", "end-to-end", "design"],
+        inputs="Target protein / constraints",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="LinearDesign",
+        model_type="generative",
+        category="CDS Optimization",
+        description="Simultaneously optimizes mRNA sequence for codon usage and minimum free energy structure. Uses dynamic programming for global optimality.",
+        repository="github.com/LinearDesignSoftware/LinearDesign",
+        repository_url="https://github.com/LinearDesignSoftware/LinearDesign",
+        deployment="embedded",
+        version="1.0",
+        paper="Zhang et al., Algorithm for optimized mRNA design improves stability and immunogenicity, Nature (2023)",
+        paper_url="https://doi.org/10.1038/s41586-023-06127-z",
+        icon="📐",
+        tags=["generative", "CDS", "codon optimization", "structure"],
+        inputs="CDS only",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="mRNAid (Merck)",
+        model_type="generative",
+        category="mRNA Optimization",
+        description="Multi-objective mRNA optimization tool. Simultaneously optimizes GC content, codon usage, MFE, and uridine depletion.",
+        repository="github.com/Merck/mRNAid",
+        repository_url="https://github.com/Merck/mRNAid",
+        deployment="both",
+        version="1.0",
+        paper="Medina-Inojosa et al., mRNAid (2024)",
+        paper_url="https://github.com/Merck/mRNAid",
+        icon="💊",
+        tags=["generative", "optimization", "multi-objective", "Merck"],
+        inputs="CDS only",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="CodonTransformer",
+        model_type="generative",
+        category="Codon Optimization",
+        description="Transformer-based codon optimizer supporting 164 organisms. Generates optimized CDS from protein sequences using organism-specific codon preferences.",
+        repository="huggingface.co/Adibvafa/CodonTransformer",
+        repository_url="https://huggingface.co/Adibvafa/CodonTransformer",
+        deployment="embedded",
+        version="1.5",
+        paper="Farhadi et al., CodonTransformer (2024)",
+        paper_url="https://huggingface.co/Adibvafa/CodonTransformer",
+        icon="🔄",
+        tags=["generative", "codon optimization", "transformer", "multi-species"],
+        inputs="Protein sequence",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="UTRGAN",
+        model_type="generative",
+        category="UTR Generation",
+        description="Generative adversarial network for designing functional 5' UTR sequences. Generates UTRs with target expression levels.",
+        repository="github.com/ciceklab/UTRGAN",
+        repository_url="https://github.com/ciceklab/UTRGAN",
+        deployment="embedded",
+        version="1.0",
+        paper="Daskalakis et al., UTRGAN, NeurIPS Workshop (2022)",
+        paper_url="https://github.com/ciceklab/UTRGAN",
+        icon="🎲",
+        tags=["generative", "UTR", "GAN", "expression"],
+        inputs="Target expression level",
+    ))
+
+    catalog.append(ModelCatalogEntry(
+        name="iCodon",
+        model_type="generative",
+        category="Codon Stability Optimization",
+        description="Codon optimization tool focusing on mRNA stability. Uses codon influence on mRNA stability to guide synonymous substitutions.",
+        repository="github.com/santiago1234/iCodon",
+        repository_url="https://github.com/santiago1234/iCodon",
+        deployment="embedded",
+        version="1.0",
+        paper="Diez et al., iCodon customizes gene expression based on codon influence on mRNA stability, Genome Biol (2022)",
+        paper_url="https://doi.org/10.1186/s13059-021-02571-y",
+        icon="🧊",
+        tags=["generative", "codon optimization", "stability", "half-life"],
+        inputs="CDS only",
+    ))
+
+    return catalog
+
+
+# Category constants for filtering
+ANALYTICAL_CATEGORIES = [
+    "Structure Prediction",
+    "UTR Scoring",
+    "Stability / Degradation",
+    "Stability / Half-life",
+    "Foundation Model",
+    "Translation Efficiency",
+]
+
+GENERATIVE_CATEGORIES = [
+    "Full mRNA Design",
+    "CDS Optimization",
+    "mRNA Optimization",
+    "Codon Optimization",
+    "UTR Generation",
+    "Codon Stability Optimization",
+]
+
+ALL_CATEGORIES = sorted(set(ANALYTICAL_CATEGORIES + GENERATIVE_CATEGORIES))
+
+FILTER_OPTIONS = [
+    "All",
+    "Analytical",
+    "Generative",
+    "Structure",
+    "Stability",
+    "Codon",
+    "UTR",
+    "Foundation",
+]