Default endpoints to the deployed backend

DEPLOY.md

@@ -1,257 +0,0 @@
-# Deploying Conformer
-
-## The sizing question, first
-
-Everything downstream depends on one number, so measure it before choosing a platform.
-
-`braid_tok/tokenizer.json` in your repo has a **151-token `WordLevel` vocabulary**. At a
-768-dimensional hidden size the embedding matrix is 151 × 768 ≈ **116 000 parameters**. For
-comparison, RoBERTa-base spends 38 M parameters on its 50k-token embedding alone. Your
-sequences are short too — the starter molecules tokenise to 9–21 tokens, and `MAX_LENGTH=128`
-is generous headroom.
-
-So BRAIDBERTa is somewhere between a few million and ~85 M parameters, running on sequences
-an order of magnitude shorter than natural-language models. **You do not need a GPU.** On two
-CPU cores a batch of 32 molecules is tens of milliseconds. A GPU would sit idle and cost
-$0.40–$2.00/hour to do so.
-
-Confirm the exact figure before you publish:
-
-```python
-from transformers import AutoModelForMaskedLM
-m = AutoModelForMaskedLM.from_pretrained("aakothari/BRAIDBERTa")
-print(sum(p.numel() for p in m.parameters()) / 1e6, "M parameters")
-print(m.config)
-```
-
-If that prints under ~300 M, everything below holds. If it prints over ~1 B — which would be
-surprising for a ZINC-100k corpus — skip to *Scale path* at the end.
-
----
-
-## Recommendation
-
-> **Correction (July 2026).** An earlier version of this document recommended a
-> Docker Space on the free CPU tier. That is no longer available: Docker Spaces
-> require a paid plan, and the `cpu-basic` flavour now needs PRO. The free tier
-> runs **Gradio** Spaces on ZeroGPU. The recommendation below reflects that.
-
-**A Hugging Face Space using the Gradio SDK, with Conformer's FastAPI app mounted
-as the root application.**
-
-The reasoning that mattered before still holds: serving the page from the same
-app that serves the models eliminates CORS, the second deployment, environment-
-specific base URLs, and the browser-side token. What changes is the wrapper, not
-the architecture. `gr.mount_gradio_app` accepts an existing FastAPI application
-and returns it, so `backend.py` stays the root and is not modified at all —
-`app.py` is nine lines of substance around it.
-
-You end up on the free tier, on the platform where your weights already live and
-where reviewers look for demos.
-
-### Comparison
-
-| Option | Verdict |
-|---|---|
-| **HF Space, Gradio SDK** | **Recommended.** Free. `app.py` wraps the unmodified backend; every route stays where it was. Hardware is ZeroGPU on the free tier — the app is CPU-bound and simply never requests the GPU, which is fine but is the one thing to verify after your first deploy. |
-| **HF Space, Docker SDK** | Exactly what was built, zero wrapper, but now needs a paid plan. PRO is ~$9/month and also unlocks `cpu-basic`. Worth it if you want the Dockerfile verbatim and the simplest mental model. |
-| **Google Cloud Run** | **Best non-HF option.** Deploys the existing Dockerfile unchanged — `PORT` is already read from the environment. Generous always-free tier, scales to zero. Needs a GCP account with billing enabled even to stay inside the free tier, which is the main friction. Cold start 10–30 s; `--min-instances=1` removes it for roughly $10–15/month. |
-| **Vercel frontend + backend elsewhere** | **Backend on Vercel remains a non-starter**: serverless functions cap at 250 MB unzipped and RDKit (~120 MB) + torch CPU (~200 MB) + transformers exceed that before your code loads. |
-| **Modal** | Good fit — scale-to-zero containers, ~$30/month in free credits, `@modal.enter()` loads weights once per container. More platform-specific code than a Space. |
-| **Render / Fly.io free tiers** | Memory-constrained (512 MB and 256 MB respectively by default). RDKit plus torch will not fit comfortably. Viable only on paid instances. |
-| **AWS App Runner / ECS Fargate** | Works, ~$15–30/month always-on, most operational overhead. Only if you are already in AWS. |
-| **RunPod** | GPU rental. Wrong tool — you are CPU-bound on a small model. |
-
-### Cost
-
-| | Monthly |
-|---|---|
-| HF Space, Gradio SDK, free tier | **$0** |
-| HF PRO (unlocks Docker + cpu-basic) | ~$9 |
-| HF Space, CPU Upgrade (8 vCPU) | ~$21 |
-| Cloud Run, demo traffic, scale-to-zero | ~$0–5 |
-| Cloud Run, `min-instances=1` | ~$10–15 |
-| Fargate always-on | ~$15–30 |
-| Any GPU instance | $290+ — and unnecessary |
-
----
-
-## Deployment steps
-
-Five files go in the Space: `app.py`, `backend.py`, `conformer.html`,
-`requirements.txt`, and `README.md` carrying the Space card frontmatter.
-
-On **huggingface.co/new-space**, choose:
-
-- **SDK** → Gradio → **Blank**
-- **Hardware** → ZeroGPU (the free option)
-- **Visibility** → Public
-
-Then:
-
-```bash
-git clone https://huggingface.co/spaces/<you>/conformer
-cd conformer
-cp /path/to/{app.py,backend.py,conformer.html,requirements.txt,README.md} .
-git add -A && git commit -m "Conformer" && git push
-```
-
-The first build takes ~10 minutes, mostly torch and RDKit. Watch the Space's
-**Logs** tab; you want to see `serving conformer.html`.
-
-Verify in this order — each rules out a distinct failure:
-
-```bash
-curl https://<you>-conformer.hf.space/health      # converters loaded?
-curl https://<you>-conformer.hf.space/version     # right model revisions?
-curl -X POST https://<you>-conformer.hf.space/convert/braid \
-  -H 'Content-Type: application/json' -d '{"smiles":"CCO"}'
-```
-
-Then open the Space root and confirm the workbench renders, the backend shows
-**connected** on stage 02, and Embed set returns vectors that are not all
-identical.
-
-### Running the Dockerfile instead
-
-The `Dockerfile` is still in the bundle and still correct. It targets a paid
-Docker Space or Cloud Run:
-
-```bash
-# local check against the exact image that will run in production
-docker build -t conformer . && docker run --rm -p 7860:7860 conformer
-
-# Cloud Run
-gcloud run deploy conformer --source . --region us-central1 \
-  --cpu 2 --memory 4Gi --allow-unauthenticated
-```
-
-`PORT` is read from the environment, so Cloud Run needs no code change. Drop
-`gradio` from `requirements.txt` on this path — `backend.py` never imports it.
-
-### If the model repos are private
-
-Add `HF_TOKEN` under **Settings → Variables and secrets**. `backend.py` reads it
-via `os.getenv("HF_TOKEN")` for both model loading and the `/tokenizer` route.
-Never put it in the Dockerfile — `ARG` and `ENV` values persist in image history.
-
-## Code changes (already applied)
-
-1. **Same-origin resolution.** The frontend now reads `location.origin` when served over
-   http(s) and falls back to `http://127.0.0.1:8000` when opened as a `file://`. One build
-   works both as a local dev loop and as a deployed Space, with no configuration.
-
-2. **The backend serves the frontend.** `GET /` returns `conformer.html`. No second
-   deployment, no CORS.
-
-3. **CORS is now opt-in.** `ALLOWED_ORIGINS` (comma-separated) adds the middleware only if
-   set. Same-origin deployment leaves it empty. The previous `allow_origins=["*"]` was fine
-   for a local file but should never face the public internet.
-
-4. **No browser token needed.** When the page detects it is self-hosted, the encoder stages
-   call the backend directly. The Hugging Face token path remains for the `file://` dev case.
-
-5. **Batch ceilings.** `MAX_BATCH` (default 64) returns 413 rather than letting one request
-   allocate unbounded memory.
-
-6. **Pinned model revisions.** `BRAID_REV` / `DEEP_REV` env vars are passed as `revision=` to
-   `from_pretrained`. Default `main`; set to commit SHAs before a release.
-
-7. **`GET /version`** returns git SHA, model repos, pinned revisions, and installed package
-   versions.
-
-8. **`PRELOAD=1`** loads both models at startup so the first visitor doesn't absorb it.
-
----
-
-## Model weights
-
-**Do not vendor the weights into git.** They already have a canonical home on the Hub, which
-is versioned, mirrored and citable.
-
-The Dockerfile prefetches them at *build* time into the image layer. That trades image size
-(~1–2 GB) for a warm start — the right trade for a demo, where the first impression is
-someone clicking a link. To keep the image small instead, delete the prefetch `RUN` and the
-models will download on first request into `HF_HOME`.
-
-For the paper release, pin by commit SHA rather than `main`:
-
-```bash
-# get the SHA
-python -c "from huggingface_hub import HfApi; \
-print(HfApi().model_info('aakothari/BRAIDBERTa').sha)"
-
-# then, in the Space settings
-BRAID_REV=<sha>
-DEEP_REV=<sha>
-```
-
-`main` can move. A reader reproducing your numbers eighteen months from now needs the weights
-you actually used.
-
----
-
-## Authentication
-
-For a public research demo the correct answer is **no user authentication**. Requiring
-sign-up defeats the purpose, and there is nothing sensitive behind the endpoints — users
-supply their own molecules and get vectors back.
-
-What you do need is abuse resistance, in this order:
-
-1. **`MAX_BATCH`** — already in place, caps per-request work.
-2. **Rate limiting** — add `slowapi` if the Space attracts scripted traffic:
-   ```python
-   from slowapi import Limiter
-   from slowapi.util import get_remote_address
-   limiter = Limiter(key_func=get_remote_address, default_limits=["60/minute"])
-   app.state.limiter = limiter
-   ```
-3. **HF Spaces already fronts you** with its own infrastructure-level protection.
-
-Keep `HF_TOKEN` server-side as a Space secret if the repos are private. The browser should
-never hold a credential in the deployed configuration — and note that the token you pasted
-into our conversation should be rotated regardless.
-
----
-
-## Reproducibility for a paper release
-
-| Artefact | Action |
-|---|---|
-| Code | Tag the release in the `braid` repo. Archive to **Zenodo** for a DOI (GitHub → Zenodo integration, then cut a release). |
-| Container | Pin the base image by digest: `FROM python:3.11-slim@sha256:...`. `python:3.11-slim` is a moving tag. |
-| Dependencies | Ship a full `pip freeze > requirements.lock.txt` alongside the top-level pins. |
-| Weights | Pin `BRAID_REV` / `DEEP_REV` to SHAs. Record them in the paper. |
-| Deployment | Spaces are git repos — the Space itself is a citable snapshot. |
-| Provenance at runtime | `GET /version` returns the whole set. A reviewer can check what they are looking at. |
-| Determinism | Note in the paper that embeddings are float32 CPU inference; results are deterministic given fixed weights and `MAX_LENGTH`, but will differ in the last decimal place from GPU inference. |
-
-Add a `CITATION.cff` to the repo root so GitHub renders a citation widget, and put the Space
-URL, the Zenodo DOI and the model revision SHAs in the paper's artefact statement.
-
-**One caveat to state explicitly in any write-up**: BRAID has two encoding modes, and they
-are not interchangeable. Record which one BRAIDBERTa was pretrained on, and make sure the
-demo's default matches. The workbench exposes the toggle and the dataset card records the
-setting, but the burden of matching it to the checkpoint is yours.
-
----
-
-## Scale path
-
-Move off Spaces when either is true: sustained concurrency above roughly 4–8 simultaneous
-users, or the model turns out to be far larger than the tokenizer implies.
-
-Cloud Run is the natural next step because the same container image deploys unchanged:
-
-```bash
-gcloud run deploy conformer \
-  --source . --region us-central1 \
-  --cpu 2 --memory 4Gi \
-  --min-instances 1 \          # removes cold starts, ~$10-15/mo
-  --max-instances 10 \
-  --allow-unauthenticated
-```
-
-Only reach for a GPU if you measure a real bottleneck. For a 151-token vocabulary on
-sub-30-token sequences, you almost certainly never will.

app.py

@@ -1,155 +0,0 @@
-"""
-Entry point for a Hugging Face Space using the **Gradio SDK**.
-
-Why this file exists: Docker Spaces require a paid plan, and the free CPU
-flavour now needs PRO. The free tier runs Gradio Spaces on ZeroGPU. Gradio is
-itself built on FastAPI, and `gr.mount_gradio_app` accepts an existing FastAPI
-application and returns it — so Conformer's backend stays the root application,
-serving the workbench at `/` exactly as it does locally, with a small Gradio
-surface mounted at `/gradio` so the Space is recognisably a Gradio app.
-
-Nothing in backend.py changes. This is a wrapper, not a fork.
-
-    Space settings:  SDK = Gradio,  hardware = ZeroGPU (free) or CPU basic
-    Files required:  app.py, backend.py, conformer.html, requirements.txt
-
-ZeroGPU note
-------------
-ZeroGPU terminates any Space whose process registers no `@spaces.GPU`
-function at startup:
-
-    runtime error: No @spaces.GPU function detected during startup
-
-Conformer is CPU-bound and does not need a GPU, so `gpu_probe` below is the
-one decorated function in the process. It is not a stub for its own sake: it
-reports the accelerator the Space was actually granted, which is the single
-thing DEPLOY.md says to verify after a first deploy, and it holds the GPU for
-a couple of seconds rather than for the lifetime of the container.
-
-The FastAPI routes stay on CPU. `backend.device()` memoises its answer at
-first call, when no GPU is attached, so it resolves to "cpu" and every cached
-model in `backend._cache` stays there. `gpu_probe` deliberately does not touch
-that cache — a model moved to CUDA inside a ZeroGPU window becomes unusable
-once the window closes.
-"""
-
-from __future__ import annotations
-
-import os
-
-import gradio as gr
-
-# The FastAPI application, unmodified. Importing it registers every route:
-# /, /health, /version, /convert/*, /tokenizer/*, /models/*/pipeline/*
-from backend import MODELS, app as api
-
-# `spaces` exists only on Hugging Face hardware. Degrade to a no-op decorator
-# so this file still runs locally, on Cloud Run, and anywhere else.
-try:
-    import spaces
-
-    ZEROGPU = True
-except ImportError:  # pragma: no cover - depends on host
-    ZEROGPU = False
-
-    class _Shim:
-        @staticmethod
-        def GPU(*args, **kwargs):
-            def wrap(fn):
-                return fn
-
-            return wrap
-
-    spaces = _Shim()  # type: ignore[assignment]
-
-
-@spaces.GPU(duration=10)
-def gpu_probe() -> str:
-    """Report the accelerator this Space was granted. Registers ZeroGPU."""
-    try:
-        import torch
-    except ImportError:
-        return "torch is not installed — encoder routes will return 501."
-
-    if torch.cuda.is_available():
-        name = torch.cuda.get_device_name(0)
-        total = torch.cuda.get_device_properties(0).total_memory / 1e9
-        return (
-            f"GPU attached: {name} ({total:.0f} GB).\n\n"
-            "Conformer does not use it — the model is small enough that CPU "
-            "inference is faster than the round trip. The FastAPI routes at / "
-            "run on CPU."
-        )
-    return (
-        "No GPU attached; running on CPU. This is the expected and intended "
-        "state for Conformer."
-    )
-
-
-_INTRO = f"""
-# Conformer
-
-A browser workbench for the BRAID molecular line notation and the
-BRAIDBERTa / DeepBERTa encoders.
-
-### → [Open the workbench](/)
-
-Structure parsing, drawing, descriptors and fingerprints run in your browser via
-RDKit's WebAssembly build. BRAID conversion and the encoders run on this Space,
-on CPU.
-
-**Models**
-- `{MODELS['braid']}`
-- `{MODELS['deep']}`
-
-**API** — the routes below are open, no key required.
-
-| Route | Purpose |
-|---|---|
-| `POST /convert/braid` | SMILES → BRAID, plus the token stream the model consumes |
-| `POST /convert/braid/decode` | BRAID → SMILES |
-| `POST /convert/braid/batch` | one request for a whole set |
-| `POST /convert/selfies` | SMILES → SELFIES |
-| `POST /models/{{owner}}/{{name}}/pipeline/feature-extraction` | embeddings |
-| `POST /models/{{owner}}/{{name}}/pipeline/fill-mask` | masked-token probe |
-| `GET /version` | git SHA, pinned model revisions, package versions |
-
-```bash
-curl -X POST https://<this-space>.hf.space/convert/braid \\
-  -H 'Content-Type: application/json' \\
-  -d '{{"smiles":"CC(=O)Oc1ccccc1C(=O)O","aromatic":true}}'
-```
-"""
-
-with gr.Blocks(title="Conformer", analytics_enabled=False) as demo:
-    gr.Markdown(_INTRO)
-
-    with gr.Accordion("Hardware check", open=False):
-        gr.Markdown(
-            "Conformer is CPU-bound. This button confirms what the Space was "
-            "allocated and releases it immediately."
-        )
-        _btn = gr.Button("Check accelerator")
-        _out = gr.Markdown()
-        _btn.click(gpu_probe, inputs=None, outputs=_out)
-
-# Conformer's FastAPI app stays at the root; Gradio is mounted beside it.
-app = gr.mount_gradio_app(api, demo, path="/gradio")
-
-
-if __name__ == "__main__":
-    import uvicorn
-
-    # The Space runner executes this file as a script and expects it to block
-    # by serving; it does not launch anything itself. Remove this and the
-    # container exits 0 having served nothing.
-    #
-    # On a Space, 7860 is the port the proxy forwards to, and it is the only
-    # port that works. PORT has been observed set to 7861 in the environment,
-    # which is held by the proxy itself — binding it fails with EADDRINUSE.
-    # So ignore PORT here and honour it everywhere else, where it is how
-    # Cloud Run and friends communicate the port.
-    on_space = bool(os.getenv("SPACE_ID") or os.getenv("SPACE_REPO_ID"))
-    port = 7860 if on_space else int(os.getenv("PORT", "7860"))
-
-    uvicorn.run(app, host="0.0.0.0", port=port)

backend.py

@@ -1,545 +0,0 @@
-"""
-Conformer backend — optional.
-
-Serves BRAIDBERTa and DeepBERTa from your own machine using the same route
-shape the workbench already calls, so nothing in the frontend has to change.
-
-    # converters — light, no GPU, no torch
-    pip install "fastapi>=0.110" "uvicorn[standard]" rdkit selfies
-    pip install git+https://github.com/AayushK-othari/braid.git
-
-    # encoders — only if you want embeddings and fill-mask
-    pip install torch transformers
-
-    python backend.py
-
-torch and transformers are imported lazily, so the BRAID and SELFIES routes
-work on a machine with neither installed. The encoder routes return a clear
-501 in that case rather than failing obscurely.
-
-Then in Conformer: header -> "Encoders offline" -> Inference endpoint:
-
-    http://127.0.0.1:8000/models
-
-Why you might want this: Hugging Face's serverless inference does not host
-every custom architecture, and feature-extraction on a private or unusual
-encoder often is not available there. Running locally sidesteps that entirely,
-and your structures never leave the machine.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-from contextlib import asynccontextmanager
-import subprocess
-from pathlib import Path
-from typing import Any
-
-from fastapi import FastAPI, HTTPException, Request
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import FileResponse, HTMLResponse
-from pydantic import BaseModel
-
-logging.basicConfig(level=logging.INFO, format="%(levelname)s  %(message)s")
-log = logging.getLogger("conformer")
-
-MAX_LENGTH = int(os.getenv("MAX_LENGTH", "128"))
-MAX_BATCH = int(os.getenv("MAX_BATCH", "64"))      # refuse absurd public requests
-HERE = Path(__file__).parent
-
-# The page is looked for beside this file. Accept the obvious names, fall back
-# to "the only .html in the folder", and allow an explicit override, because
-# "404" is a miserable thing to debug when the file is simply one directory over.
-FRONTEND_NAMES = ("conformer.html", "app.html", "index.html")
-
-
-def find_frontend() -> Path | None:
-    override = os.getenv("FRONTEND_PATH")
-    if override:
-        p = Path(override).expanduser()
-        return p if p.is_file() else None
-    for name in FRONTEND_NAMES:
-        p = HERE / name
-        if p.is_file():
-            return p
-    loose = sorted(HERE.glob("*.html"))
-    return loose[0] if len(loose) == 1 else None
-
-# Pin model revisions for reproducibility. Set these to commit SHAs before a
-# paper release so a reader gets byte-identical weights, not "whatever main is".
-MODELS = {
-    "braid": os.getenv("BRAID_REPO", "aakothari/BRAIDBERTa"),
-    "deep": os.getenv("DEEP_REPO", "aakothari/DeepBERTa_zinc_base_100k_v4"),
-}
-REVISIONS = {
-    MODELS["braid"]: os.getenv("BRAID_REV", "main"),
-    MODELS["deep"]: os.getenv("DEEP_REV", "main"),
-}
-
-# torch and transformers are imported lazily. The converter routes below are
-# useful on their own, and there is no reason to require a 2 GB install to
-# turn SMILES into BRAID.
-_DEVICE = None
-
-
-def device() -> str:
-    global _DEVICE
-    if _DEVICE is None:
-        try:
-            import torch
-            _DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
-        except ImportError:
-            _DEVICE = "no-torch"
-    return _DEVICE
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """PRELOAD=1 pays the model-loading cost at boot so the first user does not."""
-    if os.getenv("PRELOAD") == "1":
-        for repo in MODELS.values():
-            try:
-                load(repo)
-                log.info("preloaded %s", repo)
-            except Exception as exc:              # noqa: BLE001
-                log.warning("preload failed for %s: %s", repo, exc)
-    yield
-
-
-app = FastAPI(title="Conformer backend", lifespan=lifespan)
-# A page opened from disk sends "Origin: null" and is cross-origin to
-# 127.0.0.1, so the local dev loop needs CORS. The default is therefore "*".
-#
-# In a same-origin deployment (this app serving conformer.html at /) no
-# cross-origin request happens at all, so the Dockerfile sets ALLOWED_ORIGINS=""
-# to drop the middleware entirely. Set it to an explicit origin list if you ever
-# host the page separately.
-_origins = [o for o in os.getenv("ALLOWED_ORIGINS", "*").split(",") if o]
-if _origins:
-    app.add_middleware(
-        CORSMiddleware,
-        allow_origins=_origins,
-        allow_methods=["POST", "GET", "OPTIONS"],
-        allow_headers=["Content-Type", "Authorization"],
-    )
-
-_cache: dict[str, tuple[Any, Any]] = {}
-
-
-def load(repo: str):
-    """Load and memoise a tokenizer + masked-LM pair."""
-    if repo not in _cache:
-        try:
-            from transformers import AutoModelForMaskedLM, AutoTokenizer
-        except ImportError as exc:
-            raise HTTPException(
-                501, "pip install torch transformers to serve the encoders"
-            ) from exc
-        log.info("loading %s on %s", repo, device())
-        rev = REVISIONS.get(repo, "main")
-        token = os.getenv("HF_TOKEN") or None      # only needed for private repos
-        tok = AutoTokenizer.from_pretrained(repo, revision=rev, token=token)
-        mdl = AutoModelForMaskedLM.from_pretrained(
-            repo, revision=rev, token=token, output_hidden_states=True
-        )
-        mdl.eval().to(device())
-        _cache[repo] = (tok, mdl)
-    return _cache[repo]
-
-
-class Payload(BaseModel):
-    inputs: Any = None
-    options: dict | None = None
-
-
-@app.get("/health")
-def health():
-    """The workbench calls this on connect to discover which converters exist."""
-    return {
-        "ok": True,
-        "device": device(),
-        "loaded": list(_cache),
-        "converters": {
-            "braid": BRAID_OK,
-            "selfies": SELFIES_OK,
-        },
-    }
-
-
-@app.post("/models/{owner}/{name}/pipeline/feature-extraction")
-def feature_extraction(owner: str, name: str, body: Payload):
-    """Return [batch][sequence][hidden] — the workbench pools client-side,
-    so mean vs CLS stays a choice you make in the interface."""
-    repo = f"{owner}/{name}"
-    texts = body.inputs if isinstance(body.inputs, list) else [body.inputs]
-    texts = [str(t) for t in texts if t is not None]
-    if not texts:
-        raise HTTPException(400, "no inputs")
-    if len(texts) > MAX_BATCH:
-        raise HTTPException(413, f"batch of {len(texts)} exceeds MAX_BATCH={MAX_BATCH}")
-    try:
-        tok, mdl = load(repo)
-    except HTTPException:
-        raise                                     # keep 501 "install torch" as-is
-    except Exception as exc:                      # noqa: BLE001
-        raise HTTPException(503, f"could not load {repo}: {exc}") from exc
-
-    import torch
-    with torch.no_grad():
-        enc = tok(texts, padding=True, truncation=True,
-                  max_length=MAX_LENGTH, return_tensors="pt").to(device())
-        hidden = mdl(**enc).hidden_states[-1]     # (B, T, H)
-        out = []
-        mask = enc["attention_mask"].bool()
-        for i in range(hidden.size(0)):
-            keep = hidden[i][mask[i]]             # drop padding so mean-pooling is honest
-            out.append(keep.cpu().tolist())
-    return out
-
-
-@app.post("/models/{owner}/{name}/pipeline/fill-mask")
-def fill_mask(owner: str, name: str, body: Payload):
-    repo = f"{owner}/{name}"
-    text = body.inputs if isinstance(body.inputs, str) else str(body.inputs)
-    try:
-        tok, mdl = load(repo)
-    except HTTPException:
-        raise                                     # keep 501 "install torch" as-is
-    except Exception as exc:                      # noqa: BLE001
-        raise HTTPException(503, f"could not load {repo}: {exc}") from exc
-
-    if tok.mask_token is None:
-        raise HTTPException(400, f"{repo} has no mask token")
-    # accept whichever mask spelling the user typed
-    for alias in ("[MASK]", "<mask>", "<MASK>"):
-        text = text.replace(alias, tok.mask_token)
-    if tok.mask_token not in text:
-        raise HTTPException(400, f"input contains no {tok.mask_token}")
-
-    import torch
-    with torch.no_grad():
-        enc = tok(text, return_tensors="pt", truncation=True,
-                  max_length=MAX_LENGTH).to(device())
-        logits = mdl(**enc).logits[0]
-        pos = (enc["input_ids"][0] == tok.mask_token_id).nonzero()[0, 0]
-        top = logits[pos].softmax(-1).topk(10)
-    return [[
-        {
-            "token": int(idx),
-            "token_str": tok.convert_ids_to_tokens(int(idx)),
-            "score": float(score),
-        }
-        for score, idx in zip(top.values, top.indices)
-    ]]
-
-
-@app.get("/tokenizer/{owner}/{name}")
-def tokenizer_json(owner: str, name: str):
-    """Hand the browser a tokenizer.json for a repo.
-
-    The page cannot always fetch this itself: the repo may be private, the
-    files may not be laid out where a URL guess would find them, or the Hub may
-    not send CORS headers for that path. This route sidesteps all three, because
-    the server has huggingface_hub, transformers and (optionally) HF_TOKEN.
-    """
-    repo = f"{owner}/{name}"
-    rev = REVISIONS.get(repo, "main")
-    token = os.getenv("HF_TOKEN") or None
-    tried = []
-
-    # 1. the file itself, if the repo ships one
-    try:
-        from huggingface_hub import hf_hub_download
-        path = hf_hub_download(repo, "tokenizer.json", revision=rev, token=token)
-        return json.loads(Path(path).read_text(encoding="utf-8"))
-    except Exception as exc:                      # noqa: BLE001
-        tried.append(f"tokenizer.json: {exc}")
-
-    # 2. rebuild it — covers repos carrying only vocab.json + merges.txt
-    try:
-        from transformers import AutoTokenizer
-        tok = AutoTokenizer.from_pretrained(repo, revision=rev, token=token)
-        backend_tok = getattr(tok, "backend_tokenizer", None)
-        if backend_tok is None:
-            raise RuntimeError("not a fast tokenizer, cannot serialise")
-        return json.loads(backend_tok.to_str())
-    except Exception as exc:                      # noqa: BLE001
-        tried.append(f"AutoTokenizer: {exc}")
-
-    raise HTTPException(502, f"no tokenizer for {repo} (rev {rev}) — " + " | ".join(tried))
-
-
-@app.get("/repo-check/{owner}/{name}")
-def repo_check(owner: str, name: str):
-    """Does this repo exist, and can we see it? Distinguishes 404 from 401."""
-    repo = f"{owner}/{name}"
-    try:
-        from huggingface_hub import HfApi
-        info = HfApi().model_info(repo, token=os.getenv("HF_TOKEN") or None)
-        return {
-            "repo": repo, "exists": True, "private": info.private,
-            "sha": info.sha,
-            "files": sorted(f.rfilename for f in info.siblings)[:60],
-        }
-    except Exception as exc:                      # noqa: BLE001
-        return {"repo": repo, "exists": False, "error": str(exc)[:300]}
-
-
-@app.post("/models/{owner}/{name}/pipeline/tokenize")
-def tokenize(owner: str, name: str, body: Payload):
-    repo = f"{owner}/{name}"
-    texts = body.inputs if isinstance(body.inputs, list) else [body.inputs]
-    tok, _ = load(repo)
-    return [{"tokens": tok.tokenize(str(t)), "ids": tok(str(t))["input_ids"]}
-            for t in texts]
-
-
-# --------------------------------------------------------------------------- #
-# Converters
-#
-# Both of these call the *reference implementations*, not reimplementations.
-# BRAID in particular is not ported to JavaScript anywhere in this project:
-# braids/codec.py depends on RWMol, GetPeriodicTable().GetValenceList(),
-# AssignCIPLabels and SetDoubleBondNeighborDirections, none of which RDKit's
-# WebAssembly build (MinimalLib) exposes. A hand-rolled JS version would
-# diverge precisely at valence clamping and CIP-based stereo resolution — the
-# parts that are hardest to notice going wrong. So the browser asks this
-# server, and this server runs your code.
-#
-#     pip install git+https://github.com/AayushK-othari/braid.git
-#     pip install selfies
-# --------------------------------------------------------------------------- #
-
-try:
-    from braids import braid_to_smiles, smiles_to_braid
-    from braids.tokenizer import tokenize as braid_tokenize
-    BRAID_OK = True
-except ImportError:                               # pragma: no cover
-    BRAID_OK = False
-    log.warning("braids not installed — /convert/braid will return 501")
-
-try:
-    import selfies as sf
-    SELFIES_OK = True
-except ImportError:                               # pragma: no cover
-    SELFIES_OK = False
-    log.warning("selfies not installed — /convert/selfies will return 501")
-
-
-class ConvertIn(BaseModel):
-    smiles: str | None = None
-    text: str | None = None                       # for decode
-    aromatic: bool = False                        # BRAID Kekule vs aromatic mode
-    clamp: bool = True                            # BRAID decoder valence clamping
-
-
-class BatchIn(BaseModel):
-    smiles: list[str] = []
-    aromatic: bool = False
-
-
-def _need(flag: bool, pkg: str, hint: str):
-    if not flag:
-        raise HTTPException(501, f"{pkg} is not installed — {hint}")
-
-
-@app.post("/convert/braid")
-def convert_braid(body: ConvertIn):
-    """SMILES -> BRAID, via braids.smiles_to_braid.
-
-    `aromatic` picks the mode. They are NOT interchangeable: whichever you
-    pretrained on is the one you must encode with at inference time.
-    """
-    _need(BRAID_OK, "braids", "pip install git+https://github.com/AayushK-othari/braid.git")
-    smi = body.smiles or body.text
-    if not smi:
-        raise HTTPException(400, "no smiles supplied")
-    try:
-        braid = smiles_to_braid(smi, aromatic=body.aromatic)
-    except Exception as exc:                      # noqa: BLE001
-        raise HTTPException(400, f"could not encode: {exc}") from exc
-    toks = braid_tokenize(braid)
-    # BRAIDBERTa's tokenizer is WordLevel + WhitespaceSplit over a 151-token
-    # vocabulary, so the model input is the SPACE-JOINED token stream, not the
-    # raw BRAID string. Feed it the raw string and WhitespaceSplit sees one
-    # unknown word and the whole molecule collapses to <unk>.
-    return {"result": braid, "tokens": " ".join(toks), "n_tokens": len(toks)}
-
-
-@app.post("/convert/braid/decode")
-def decode_braid(body: ConvertIn):
-    """BRAID -> SMILES. With clamp=True every string decodes to something
-    sanitizable, which is the whole point of the notation."""
-    _need(BRAID_OK, "braids", "pip install git+https://github.com/AayushK-othari/braid.git")
-    s = body.text or body.smiles
-    if not s:
-        raise HTTPException(400, "no braid string supplied")
-    try:
-        return {"result": braid_to_smiles(s, clamp=body.clamp)}
-    except Exception as exc:                      # noqa: BLE001
-        raise HTTPException(400, f"could not decode: {exc}") from exc
-
-
-@app.post("/convert/braid/batch")
-def batch_braid(body: BatchIn):
-    """One request per set instead of one per molecule."""
-    _need(BRAID_OK, "braids", "pip install git+https://github.com/AayushK-othari/braid.git")
-    if len(body.smiles) > MAX_BATCH:
-        raise HTTPException(413, f"batch exceeds MAX_BATCH={MAX_BATCH}")
-    out, toks, errs = [], [], []
-    for smi in body.smiles:
-        try:
-            b = smiles_to_braid(smi, aromatic=body.aromatic)
-            out.append(b)
-            toks.append(" ".join(braid_tokenize(b)))
-            errs.append(None)
-        except Exception as exc:                  # noqa: BLE001
-            out.append(None)
-            toks.append(None)
-            errs.append(str(exc))
-    return {"results": out, "tokens": toks, "errors": errs}
-
-
-@app.post("/convert/braid/tokens")
-def braid_tokens(body: ConvertIn):
-    """BRAID string -> the token stream the model actually consumes."""
-    _need(BRAID_OK, "braids", "pip install git+https://github.com/AayushK-othari/braid.git")
-    s = body.text or body.smiles
-    if not s:
-        raise HTTPException(400, "no braid string supplied")
-    toks = braid_tokenize(s)
-    return {"tokens": toks, "text": " ".join(toks), "n_tokens": len(toks)}
-
-
-@app.post("/convert/selfies")
-def convert_selfies(body: ConvertIn):
-    """SMILES -> SELFIES via the reference implementation."""
-    _need(SELFIES_OK, "selfies", "pip install selfies")
-    smi = body.smiles or body.text
-    if not smi:
-        raise HTTPException(400, "no smiles supplied")
-    try:
-        return {"result": sf.encoder(smi)}
-    except Exception as exc:                      # noqa: BLE001
-        raise HTTPException(400, f"could not encode: {exc}") from exc
-
-
-@app.post("/convert/selfies/decode")
-def decode_selfies(body: ConvertIn):
-    _need(SELFIES_OK, "selfies", "pip install selfies")
-    s = body.text or body.smiles
-    if not s:
-        raise HTTPException(400, "no selfies string supplied")
-    try:
-        return {"result": sf.decoder(s)}
-    except Exception as exc:                      # noqa: BLE001
-        raise HTTPException(400, f"could not decode: {exc}") from exc
-
-
-@app.post("/convert/selfies/batch")
-def batch_selfies(body: BatchIn):
-    _need(SELFIES_OK, "selfies", "pip install selfies")
-    if len(body.smiles) > MAX_BATCH:
-        raise HTTPException(413, f"batch exceeds MAX_BATCH={MAX_BATCH}")
-    out, errs = [], []
-    for smi in body.smiles:
-        try:
-            out.append(sf.encoder(smi))
-            errs.append(None)
-        except Exception as exc:                  # noqa: BLE001
-            out.append(None)
-            errs.append(str(exc))
-    return {"results": out, "errors": errs}
-
-
-# --------------------------------------------------------------------------- #
-# Static frontend + provenance
-#
-# Serving the page from this same app means same-origin: no CORS, no separate
-# deployment, one URL to cite.
-# --------------------------------------------------------------------------- #
-
-@app.get("/", response_class=HTMLResponse)
-def index():
-    page = find_frontend()
-    if page:
-        return FileResponse(page, media_type="text/html")
-
-    found = sorted(f.name for f in HERE.glob("*.html"))
-    listing = ("<li><code>" + "</code></li><li><code>".join(found) + "</code></li>"
-               if found else "<li><em>no .html files here at all</em></li>")
-    return HTMLResponse(status_code=404, content=f"""<!doctype html>
-<meta charset="utf-8"><title>Frontend not found</title>
-<style>
- body{{background:#0B0E14;color:#AAB3C5;font:15px/1.65 system-ui,sans-serif;padding:48px;max-width:760px;margin:auto}}
- h1{{color:#E8ECF4;font-size:21px;margin:0 0 6px}} code{{color:#7DD3A0;font-family:ui-monospace,monospace}}
- .box{{background:#121722;border-left:3px solid #E0A458;padding:16px 20px;border-radius:8px;margin:20px 0}}
- li{{margin:4px 0}} p{{margin:12px 0}}
-</style>
-<h1>The server is running. The page is missing.</h1>
-<p>The backend is fine — it just cannot find the workbench HTML to serve.</p>
-<div class="box">
-  <p style="margin-top:0">Looked in:<br><code>{HERE}</code></p>
-  <p>For a file named <code>conformer.html</code>, <code>app.html</code> or <code>index.html</code>.</p>
-  <p style="margin-bottom:0">HTML files actually in that folder:</p>
-  <ul>{listing}</ul>
-</div>
-<p><strong>Fix:</strong> move <code>conformer.html</code> into the folder above, next to this
-script, and reload. Or point at it directly:</p>
-<p><code>set FRONTEND_PATH=C:\\path\\to\\conformer.html</code> &nbsp;(Windows cmd)<br>
-<code>$env:FRONTEND_PATH="C:\\path\\to\\conformer.html"</code> &nbsp;(PowerShell)<br>
-<code>FRONTEND_PATH=/path/to/conformer.html</code> &nbsp;(macOS / Linux)</p>
-<p>Everything else works meanwhile — <code>/health</code>, <code>/version</code>,
-<code>/convert/braid</code> and <code>/docs</code> are all up.</p>""")
-
-
-def _git_sha() -> str:
-    if os.getenv("GIT_SHA"):
-        return os.getenv("GIT_SHA")
-    try:
-        return subprocess.check_output(
-            ["git", "rev-parse", "--short", "HEAD"], cwd=HERE, stderr=subprocess.DEVNULL
-        ).decode().strip()
-    except Exception:                             # noqa: BLE001
-        return "unknown"
-
-
-@app.get("/version")
-def version():
-    """Everything a reader needs to reproduce a result from this deployment."""
-    import importlib.metadata as md
-
-    def ver(pkg):
-        try:
-            return md.version(pkg)
-        except Exception:                         # noqa: BLE001
-            return None
-
-    return {
-        "git_sha": _git_sha(),
-        "models": MODELS,
-        "revisions": REVISIONS,
-        "max_length": MAX_LENGTH,
-        "max_batch": MAX_BATCH,
-        "packages": {p: ver(p) for p in
-                     ("rdkit", "braids-mol", "selfies", "transformers", "torch", "fastapi")},
-    }
-
-
-if __name__ == "__main__":
-    import uvicorn
-
-    host = os.getenv("HOST", "127.0.0.1")
-    port = os.getenv("PORT", "8000")
-    log.info("device: %s", device())
-    page = find_frontend()
-    if page:
-        log.info("serving %s", page.name)
-        log.info("open the workbench at  http://%s:%s/", host, port)
-    else:
-        log.warning("no conformer.html / app.html / index.html found in %s", HERE)
-        log.warning("put the page there, or set FRONTEND_PATH, then reload")
-    log.info("(opening conformer.html from disk also works, but going through")
-    log.info(" the server is same-origin and avoids CORS entirely)")
-    uvicorn.run(app, host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", "8000")))

index.html

@@ -947,15 +947,21 @@ const STAGES = [
    Opened as a local file -> fall back to a dev server on localhost. */
 const SAME_ORIGIN = (location.protocol === 'http:' || location.protocol === 'https:') ? location.origin : '';
 
+/* Deployed split: this page is a Static Space, the converters and encoders
+   live on a separate service. Hardcode it so a first-time visitor gets a
+   working workbench without touching settings. Override in settings to point
+   at a local backend.py. */
+const DEPLOYED_BACKEND = 'https://braid-9wc2.onrender.com';
+
 const S = {
   mols: [], nextId: 1,
   rdkit: null, rdkitErr: '',
   hfToken: '',                                                   // memory only, never persisted
-  hfBase: SAME_ORIGIN ? SAME_ORIGIN + '/models' : 'https://router.huggingface.co/hf-inference/models',
+  hfBase: DEPLOYED_BACKEND + '/models',
   hfLegacy: 'https://api-inference.huggingface.co/models',
   models: { braid: 'aakothari/BRAIDBERTa', deep: 'aakothari/DeepBERTa_zinc_base_100k_v4' },
   adapters: { braid: null, selfies: null },
-  backend: { base: SAME_ORIGIN || 'http://127.0.0.1:8000', ok: false, converters: {}, device: '' },
+  backend: { base: DEPLOYED_BACKEND, ok: false, converters: {}, device: '' },
   braidAromatic: false,                                          // must match what BRAIDBERTa was pretrained on
   tokenizers: {}, tokOrder: [],
   bench: null,

requirements.txt

@@ -1,50 +0,0 @@
-# Pinned to the stack this project was actually validated against.
-#
-# Four constraints shape these versions, all discovered the hard way:
-#
-#   1. ZeroGPU accepts only torch 2.11.0, 2.10.0, 2.9.1 or 2.8.0.
-#   2. gradio 6.x requires huggingface-hub >= 1.2, which transformers 4.x
-#      forbids (< 1.0). gradio 5.x is the branch that coexists with the
-#      transformers 4.49 stack running locally.
-#   3. gradio and spaces are NOT pinned here. The Space builder appends
-#      `gradio[oauth,mcp]==<sdk_version from README.md>` and `spaces==<ver>`
-#      to its own pip install line. Pinning either here as well gives pip two
-#      conflicting `==` constraints on one package and the build dies with
-#      ResolutionImpossible. The gradio version lives in README.md and
-#      nowhere else.
-#   4. gradio 5.49.1 requires pydantic < 2.12, so pydantic is 2.11.10 (the
-#      highest it allows) rather than 2.13.x. FastAPI 0.139.2 is happy with
-#      it and backend.py uses only plain BaseModel, so nothing depends on
-#      the difference.
-#
-# Verified by replicating the builder's exact pip invocation on python 3.12:
-#
-#   pip install --dry-run --ignore-installed -r requirements.txt \
-#     "torch<=2.11.0" "gradio[oauth,mcp]==5.49.1" \
-#     "uvicorn>=0.14.0" "websockets>=10.4" "spaces==0.51.0"
-#
-# 102 packages, resolves clean. Re-run that before changing anything here;
-# it is much faster than discovering conflicts one Space build at a time.
-#
-# Do NOT bump transformers to 5.x without re-running the validation locally
-# first. Deploying a different major version than the one that produced your
-# numbers is how a discrepancy becomes unexplainable.
-
-# --- web layer -------------------------------------------------------------
-fastapi==0.139.2
-uvicorn[standard]==0.51.0
-pydantic==2.11.10
-
-# --- chemistry (the correctness-critical half) -----------------------------
-rdkit==2026.3.4
-selfies==2.2.0
-braids-mol @ git+https://github.com/AayushK-othari/braid.git@main
-
-# --- encoders --------------------------------------------------------------
-# No CPU-only index here: ZeroGPU expects the standard CUDA build. The app is
-# CPU-bound and simply never requests a GPU. The Space base image already
-# ships torch 2.8.0, so this pin matches rather than triggers a reinstall.
-torch==2.8.0
-transformers==4.49.0
-tokenizers==0.21.0
-huggingface-hub==0.36.2