# Molecule library and calculation history

## Search and import

The Molecule tab searches the persistent local library, PubChem, or ChEMBL.
Use a name, synonym or database identifier for online searches. Local search
matches saved names, selection aliases, identifiers and formula strings.
The catalogue opens with all saved molecules, twelve cards per page. The
full-width search field narrows the collection; Browse catalogue clears the
query and filters and returns to its first page.
Click a 2D molecule card to select it and open its rotating 3D view. Selection
is highlighted and does not start a calculation. The single Build Pathway
button processes the current selection with the chosen algorithm(s).
Starting a calculation collapses the catalogue and built-in examples
to focus on the selected molecule and its calculation. Show molecule catalogue
reveals the same cards, filters and page again, including while a job runs.
Finishing a calculation leaves the catalogue collapsed; selecting a card
keeps it open. Build Pathway is disabled while a new selection is loading.
Size means the prepared graph's atom or bond count. Local filters examine the
entire saved library; online filters inspect each page of four name matches.
They are not a database-wide search across all compounds by origin.

Result cards show molecular previews on a dark background as they scroll into
view. Local/saved results include their prepared MOL directly, avoiding a
separate API request for every card. Visible uncached online cards retrieve and
retain their structures, one at a time, when graph conversion is enabled.
Cards use 2D SVG drawings; selecting one opens the rotating, interactive 3D
view. A 2D drawing is used for the selected view if WebGL is unavailable.
The renderer preserves the supplied coordinates (which may be 2D), and does
not generate new conformers. Preview failures stay on the affected card.

Selecting a card retrieves its structure if necessary. Saved records are reused
without another provider download. Invalid/unsupported downloads are retained
with their rejection reason, rather than repeatedly fetched. Original data,
prepared MOL, hashes, transformation report and source metadata are downloadable.

Online imports explicitly project a single connected V2000 molecule to element
labels and literal bond orders, dropping pendant single-bond hydrogens and
charge/isotope/radical/stereochemical annotations. A confirmation checkbox and
per-record report describe this. Connectivity is checked before projection:
salts and mixtures are rejected, not reduced to a selected component. Aromatic
bonds are not silently rewritten. Uploaded MOL files still use the original
strict validator, preserving explicit hydrogen atoms and rejecting annotations.
Database records may have 2D rather than 3D coordinates.

## Classification and 50-molecule panel

`molecule-panel-50.json` pins 50 PubChem CIDs, downloaded graph hashes, sizes,
selection rationales and origin evidence. It spans small prebiotic controls,
amino acids/nucleobases/sugars, natural products, designed drugs, highly
repetitive graphs and difficult natural products up to palytoxin's 195 bonds.
Strychnine and sildenafil (Viagra) are included. The original 29 built-in graphs,
including the 192-bond chain, remain available and searchable separately.

Abiotic, biotic and artificial are overlapping curated tags, not exhaustive
or exclusive classes. They describe documented occurrence or a production route,
not the actual history of a sample. Extraterrestrial occurrence is identified
explicitly as the basis for an abiotic-chemistry interpretation, not a proof of
origin. Artificial covers deliberately developed synthetic/semisynthetic products;
laboratory preparation of a naturally occurring molecule alone is insufficient.
Unclassified means evidence is missing, not that a category was disproved.
n-Hexacontane remains origin-unclassified pending molecule-specific evidence.
D-ribose uses the downloaded pyranose form, not RNA's furanose form.

For other records, only explicit affirmative ChEBI/NCI descriptions contribute
origin evidence. Human blood detection, database membership and a false
`natural_product` flag do not establish origin. ChEMBL structures can inherit
evidence through a unique PubChem match on the full standard InChIKey; the
cross-reference is retained. Unresolved records remain unclassified.
Organic/inorganic uses curated conventions for the panel and a conservative
graph rule elsewhere: carbon-free structures and simple carbon oxides are
inorganic, nonmetal carbon frameworks are organic, uncertain cases unclassified.
These classifications are independent of the calculated Assembly Index.

The panel explores the proposed biosignature boundary; it does not assume that
size, origin or a reported index proves life. See [Marshall et al. (2021)](https://www.nature.com/articles/s41467-021-23258-x)
and [Seet et al. (2025)](https://doi.org/10.1021/acs.jcim.5c01964).
Paper-associated molecular/index datasets exist, but this feature does not treat
them as a verified central database of proved minima. Existing published-reference
badges remain separate from server-computed history. Bond-order conventions must
match for a numerical comparison, including the documented ketoconazole caveat.

## Previously computed values

After worker cleanup and comparison consistency checks, the API supervisor saves
each molecule run with a checked pathway, including useful results from timeout,
cancellation and resource-limit termination. A result without a checked pathway
does not create a numeric historical value. Each comparison method has its own row.
Completed results are exposed after archiving finishes. An archive failure is
reported separately and does not discard the solver result.

Cards display the smallest checked index previously found and label it `proved`
only when optimality was established. Otherwise it is a constructive `upper bound`
(Assembly Index ≤ that value). A checked pathway alone is not an optimality proof.
Matching bounds or a completed exhaustive search supplies the method's proof claim;
there is no independently machine-checked optimality certificate for every method.
Conflicting historical proof claims withdraw the card's proof label and show a
warning while retaining the valid upper bound and original audit records.

Provenance contains algorithm ID/name/source, model, UTC timestamp, time budget,
elapsed worker time, candidate count/unit, resource allocation, job/run IDs,
input-MOL SHA-256, numbered-graph SHA-256, checked-witness SHA-256, executable
SHA-256 and API-source SHA-256. Fingerprints are captured before worker launch.
Repository HEAD is supplementary: source hashes identify uncommitted deployments
as well. Operators must not replace binaries while searches are active.

The graph fingerprint ignores MOL title, coordinates and bond record ordering,
but preserves atom numbering, elements and literal bond orders. It deliberately
does not merge arbitrary isomorphic atom-renumbered records or different
hydrogen/aromatic conventions. This conservative identity can miss equivalent
records, but avoids transferring an index to a changed input graph.

Uploaded MOL bodies and complete pathways expire with normal job retention
(approximately 10 minutes); only summaries and hashes persist in shared history.
Downloaded provider structures stay in the shared library. Summaries contain no
client IP, original upload filename, uploaded MOL body or full witness. A query
for a known graph can reveal that this graph was previously calculated.
No public endpoint accepts asserted indices or proof claims.

## API

All catalogue routes use `/assemblyexplorer/api/molecules/`:

- `GET library?q=&minimum=0&maximum=999&size=bonds&chemical_class=all&origin=all&offset=0`
- `GET search?provider=pubchem&q=glycine` (same filters; four rows per page)
- `GET structure?provider=pubchem&id=750` (prepared `mol` plus provenance)
- `GET history?sha256=<numbered graph hash>` (best value and newest 50 summaries)

Local pages contain 12 records. `size` accepts atoms/bonds; chemical class accepts
all/organic/inorganic/unknown; origin accepts all/abiotic/biotic/artificial/unknown.
POST the returned `mol` to the existing assembly/molecule endpoint. Search and
import do not independently start calculation jobs or alter computation budgets.

## Isolation, persistence and operation

The computation API and workers retain PrivateNetwork=true, AF_UNIX-only sockets,
the 32-core/64-GiB aggregate cgroup and existing CPU/memory/time/output limits.
A separate `assemblycatalogue` account runs `assembly-explorer-database.service`,
with a 256-MiB memory cap, one-core quota and no solver or GPU access. It listens
only on `/run/assemblyexplorer-database/database.sock`. Its HTTP client uses fixed
HTTPS provider origins, verified TLS, disabled redirects/environment proxies,
streaming response bounds, a one-request/second aggregate provider rate,
25-second operation deadlines and at most three concurrent lookups. Public
catalogue admission is bounded per-client and globally. No Apache configuration
or other web application's service is changed.

Persistent paths:

- `/var/lib/assemblyexplorer-molecules/library.sqlite3`: originals and metadata;
  10,000-record/512-MiB logical budget, 1-GiB physical ceiling, no eviction.
- `/var/lib/assemblyexplorer-history/history.sqlite3`: server computation summaries;
  512-MiB physical ceiling, no eviction. Bound into the API's permitted runtime
  directory while the general `/var/lib` tree remains inaccessible.

Include both databases in backup policy using SQLite's online backup facility or
service-stopped copies. Automatic backup-job changes were not part of this feature.
If a budget is reached, existing records remain and new saves report failure.

Deployment uses the versioned database service/sysusers file and
`deploy/60-molecule-catalogue.conf` as an API drop-in. Create the history directory
owned by assemblyexplorer:www-data with mode 0700 before starting. Only restart
the API when no active computation workers remain. Seed/reconcile records locally:

```sh
.venv/bin/python -m assembly_api.catalogue_admin --database /var/lib/assemblyexplorer-molecules/library.sqlite3
.venv/bin/python -m assembly_api.catalogue_admin --database /var/lib/assemblyexplorer-molecules/library.sqlite3 --seed-builtins
```

## Providers and data provenance

The integration was written independently against [PubChem PUG REST](https://pubchem.ncbi.nlm.nih.gov/docs/pug-rest)
and [ChEMBL web services](https://chembl.gitbook.io/chembl-interface-documentation/web-services/chembl-data-web-services).
It does not use any published assembly-algorithm code. Algorithm implementations
and their fidelity/provenance documents are unchanged.

PubChem aggregates contributor data: retain NCBI PubChem and individual source
attribution and consult [NCBI policies](https://www.ncbi.nlm.nih.gov/home/about/policies/)
and [PubChem data sources](https://pubchem.ncbi.nlm.nih.gov/sources); do not assume
every contributor grants identical rights. ChEMBL data is attributed to EMBL-EBI
ChEMBL under [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/).
The prepared MOL and metadata identify modifications and retain that attribution.
Fetched chemistry data is not relicensed as Assembly Explorer source code.