Skip to content

Changelog

All notable changes to ChemVault will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


v0.14.8 - 2026-10-27

Added

  • Added a Murcko relationships CSV export for completed MODELABILITY INDEX analyses. Each structure contributes its single selected nearest-neighbor relationship, with scaffold identities, cyclicity, CC/CA/AC/AA transitions, and NS/ND classifications within CC. The export preserves fingerprint and analysis provenance without selecting additional neighbors or changing MODI.
  • Added official ChemVault logos in black, white, and cyan SVG variants.

Changed

  • Organized MODELABILITY INDEX downloads into two rows and two columns, with explicit file extensions and native Streamlit icons for the nearest-neighbor CSV, Murcko relationships CSV, analysis JSON, and fingerprint NPZ.
  • Displayed MODELABILITY INDEX metrics to four decimal places in the interface without reducing persisted or exported numerical precision.
  • Replaced the research-group JPEG logo with official SVG assets in Streamlit, the browser favicon, and MkDocs; included all three SVG variants in wheel and source distributions.
  • Updated the README and MkDocs usage guidance for the four exports and published installation instructions, and excluded generated MkDocs site/ output from Git.

Fixed

  • Removed stale stereochemical annotations from generated Bemis–Murcko scaffolds to prevent RDKit failures in affected structures.
  • Prevented an Arrow serialization warning in MODELABILITY INDEX details by representing the fingerprint radius as text for display.
  • Preserved literal CSV field values during import, including NULL strings, without implicit numeric or missing-value conversion.

v0.14.7 - 2026-10-14

Added

  • Added Hatchling-based Python 3.12 packaging for wheel and source distributions, with application assets and a chemvault console command that supports --help and --version and launches the installed Streamlit application without changing the caller's working directory.
  • Added a dedicated Operation history UI summary for the persisted v0.14.6 AID-completeness contract, distinguishing certified, not-certified, and unavailable source-correspondence states while preserving the recorded operation details.
  • Added an About sidebar card with the GitHub repository link and application version resolved from source or installed distribution metadata.
  • Added a four-page MkDocs Material site covering the project overview, usage, API reference, and changelog, with searchable light- and dark-mode content.
  • Added Python 3.12 GitHub Actions workflows for continuous integration, main-branch GitHub Pages artifact deployment, and manually dispatched, tag-validated PyPI Trusted Publishing.
  • Added contributor guidelines and a community code of conduct.
  • Added CITATION.cff with standardized software citation metadata, including authors, title, version, and repository information.

Changed

  • Made pyproject.toml authoritative for project metadata and runtime dependencies, and consolidated pytest discovery plus Ruff and mypy settings there; the redundant requirements.txt and pytest.ini files were removed.
  • Relocated the CHEMVAULT branding asset under docs/assets, resolved it relative to the installed modules, and included it in both wheel and source distributions while excluding generated databases and caches.
  • Relocated the active HARMONSMILE ingest adapter from modules/ to services/harmonsmile_ingest.py and updated its canonical consumers.
  • Established clean Ruff and mypy baselines through targeted import cleanup plus precise internal type annotations and narrowing, with corresponding regression coverage.
  • Updated the application identity subtitle to describe traceable target-centered bioactivity dataset construction and modelability assessment.

Fixed

  • Corrected UI terminology to distinguish the target-centered PubChem dataset, persisted CID-AID associations, build-time structured-activity retrieval, stored structured quantitative activity, and molecular structure processing from live availability or raw source coverage.
  • Resolved relative PubChem worker database paths against the caller's working directory so installed executions retain user-workspace database ownership without injecting a source-tree working directory or PYTHONPATH.
  • Handled normal Ctrl+C interruption of the installed launcher with exit status 130, avoiding a launcher traceback while preserving other subprocess exit codes and exceptions.
  • Replaced deprecated Streamlit use_container_width arguments with the equivalent width="stretch" behavior.

Removed

  • Removed the obsolete CHAMANP dependency and integration, including its adapter, use case, sidebar controls, session state, temporary and artifact handling, taxonomy resource, example input, and exclusive tests.
  • Removed obsolete manual and experimental scripts, generated JSON fixtures, and historical generated reports that were not part of the automated test suite or active application.
  • Removed the unused modules/obtener_CIDs_Pubchem.py compatibility adapter and standalone tools/db_audit.py CLI while retaining the canonical PubChem and database-audit services and their automated coverage.

Validation

  • Passed the complete local test suite: 745 tests.
  • Confirmed Ruff, mypy, and pip check complete without findings or broken requirements.
  • Confirmed the GitHub Actions CI run for commit 0f5a4e9 completed both jobs successfully, including tests, static analysis, CLI/version checks, distribution inspection, Twine validation, isolated wheel and source- distribution installations, and a strict MkDocs build.

v0.14.6 - 2026-09-24

Added

  • Added AID-level source correspondence and completeness certification for PubChem protein-search builds, using persisted (protein, AID) identities from the source enumeration observed in the same execution.
  • Added an explicit completeness contract that distinguishes terminal AIDs, row-level target exclusions, unresolved source AIDs, missing materialization, and unexpected persisted identities.
  • Added a summarized AID-completeness projection to Operation history while retaining the detailed identity-level evidence in the originating job metadata.

Changed

  • Persisted the PubChem source AID enumeration before downstream reduction and treated that persisted enumeration as the immutable denominator for later completeness assessment.
  • Finalized AID completeness only after compound_assays materialization was committed, requiring persisted (protein, AID) identities to correspond to the terminal identities derived from the same run.
  • Preserved distinct AID-to-CID acquisition outcomes for successful, failed, invalid, and missing responses, including successful responses with an explicit empty CID list.
  • Restricted structured-activity retrieval to AIDs with successful, non-empty AID-to-CID acquisition; upstream unresolved AIDs are recorded as not_attempted for downstream activity retrieval.

Fixed

  • Prevented downstream state or previously persisted assay associations from being used to reconstruct a missing or invalid source AID denominator.
  • Prevented unresolved AID acquisition states from being interpreted as valid target-level exclusions or silently contributing to a complete population.
  • Prevented stale or unexpected (protein, AID) associations in compound_assays from satisfying the current-run completeness contract.

Validation

  • Passed the complete test suite: 714 tests.
  • Confirmed git diff --check reports no whitespace errors.
  • Reconstructed the MC4R / P32245 PubChem protein-search population from a same-run source enumeration of 652 AIDs: 650 reached terminal persisted representation and 2 remained unresolved.
  • Confirmed that AIDs 540307 and 540319 were returned by the PubChem AID-to-CID batch response without a CID field and therefore remained unresolved rather than being converted to terminal or target-excluded identities; the resulting population was correctly not certified complete.
  • The completeness contract applies only to the PubChem protein-search (protein, AID) population observed in that execution. It does not certify completeness of source rows, individual CIDs, structured activity records, molecular properties, or other downstream content.

v0.14.5 - 2026-09-24

Changed

  • Updated HARMONSMILE to version 0.3.4 and adopted explicit PubChem acquisition provenance independently of molecular harmonization status.
  • Legacy HARMONSMILE cache records without explicit acquisition provenance are no longer assumed to represent successful PubChem acquisition and are eligible for reacquisition.
  • Applied row-level PubChem target-accession evidence when available to scope target-specific compound-assay associations and structured activity records.

Fixed

  • Prevented PubChem assay rows belonging to other target accessions from being attributed to the requested biological target when row-level target evidence is available.
  • Prevented failed PubChem molecular acquisitions returned as HARMONSMILE rows from being cached as reusable successful acquisitions.
  • Preserved the distinction between PubChem acquisition outcome and subsequent molecular harmonization outcome.

Validation

  • Passed the complete test suite: 695 tests.
  • Confirmed git diff --check is clean after merging PR #30 into main.
  • Revalidated Q01959 / AID 2060761 target attribution: 33 target-specific activity records across 32 CIDs were persisted from 1,503 scientific source rows, with 33 matching, 1,470 nonmatching, and 0 unattributed source rows.
  • Revalidated the seven historical MC4R CIDs that motivated the acquisition cache correction: 7/7 were reacquired with explicit PubChem_Acquisition_Status = ok, and all 13 corresponding activity_subset_Ki rows received the corrected acquisition provenance.
  • Confirmed that acquisition and harmonization remain independent: five of the seven recovered MC4R compounds subsequently reached MaxTautomersReached, while two completed harmonization successfully.

v0.14.4 - 2026-09-21

Added

  • Added paginated PubChem assay-activity retrieval for large assays using ListKey-based SID pagination, with early schema inspection to avoid unnecessary page retrieval when no supported structured activity is present.
  • Added persisted provenance for Repair activity records, including processed, successful, and failed AIDs, per-job failure diagnostics, inserted-row counts, retrieval context, and execution parameters.

Changed

  • Optimized reconstruction of activity-repair jobs by streaming compound_assays and using set-backed CID deduplication within each protein-AID job.
  • Applied the shared PubChem rate limiter at individual HTTP-request boundaries, including retries, ListKey acquisition, and paginated assay requests.
  • Clarified activity-repair progress and terminal UI states so partial failures remain visible and completed repairs no longer appear to be actively running.

Fixed

  • Prevented very large PubChem assays from failing solely because direct assay-activity CSV retrieval exceeds the supported request size.
  • Treated successfully retrieved assays with unsupported activity-result schemas as successful retrievals producing no structured activity records, rather than as failed AIDs.
  • Preserved existing structured activity records during repair and continued to insert only previously absent records.

Validation

  • Passed the complete test suite: 682 tests.
  • Confirmed git diff --check is clean.
  • Revalidated the MC4R repair workflow across 650 protein-AID jobs: 650 processed, 650 successful, 0 failed, and 0 inserted rows.
  • Confirmed that the MC4R structured-activity population remained unchanged at 9,451 records, 600 distinct AIDs, and 4,925 distinct CIDs after repair.
  • Confirmed persistence of the repair event in operation history with its execution timestamp, successful and failed AID lists, diagnostics, and inserted-row count.

v0.14.3 - 2026-09-17

Changed

  • Reorganized the MODELABILITY INDEX structural-context presentation into separate Murcko population context and nearest-neighbor scaffold-interface groups.
  • Added the already-computed same-scaffold and different-scaffold concordances to the MODELABILITY INDEX result card.
  • Renamed the result provenance caption from Calculated from to Source dataset.
  • Updated the ChemVault tagline to Target-centered bioactivity dataset curation from PubChem.
  • Preserved all MODELABILITY INDEX and Murcko scientific calculations, analytical identities, contracts, persistence behavior, and exported artifacts.

Validation

  • Passed the complete test suite: 660 tests.
  • Confirmed git diff --check is clean after merging PR #28 into main.
  • Completed Streamlit visual validation with the PPARG Morgan analysis, confirming the revised structural-context grouping and the displayed scaffold-interface concordances.

v0.14.2 - 2026-09-16

Changed

  • Extended the downloadable MODELABILITY INDEX analysis report to schema version 2, exposing the already-computed Murcko structural context at full numeric precision.
  • Added explicit serialization of Murcko population data, structural metrics, and the Murcko nearest-neighbor interface while keeping nearest-neighbor diagnostics at their existing top-level location.
  • Preserved compatibility with legacy results lacking Murcko structural context by serializing unavailable Murcko sections as empty objects.
  • Preserved all MODELABILITY INDEX and Murcko scientific calculations, analytical identities, fingerprint artifacts, nearest-neighbor CSV output, and the existing modelability_index/v1 and murcko_modelability_context/v1 contracts.

Validation

  • Passed the complete test suite: 660 tests.
  • Confirmed git diff --check is clean after merging PR #27 into main.
  • Validated the schema-v2 analysis report end to end with the MC4R Morgan analysis, including Murcko population, structural metrics, and nearest-neighbor scaffold-interface values.
  • Confirmed that the MC4R Morgan chemvault_analysis_hash is unchanged from v0.14.1, demonstrating that the export extension does not alter the scientific analysis identity.

v0.14.1 - 2026-09-15

Added

  • Added a downloadable JSON analysis report for completed MODELABILITY INDEX analyses, containing summary metrics, analysis provenance, and the nearest-neighbor tie and ambiguity diagnostics already calculated by CHEMVAULT.

Changed

  • Extended the nearest-neighbor CSV export with fingerprint_type, chemvault_analysis_hash, and population_identity so each molecular comparison remains explicitly linked to its analytical context.
  • Updated nearest-neighbor CSV and analysis-report filenames to include the fingerprint type and the first eight characters of the analysis identity, preventing ambiguity across multiple molecular representations.
  • Preserved the existing fingerprint .npz contract and all MODELABILITY INDEX scientific calculations, including population preparation, fingerprint generation, Tanimoto similarity, nearest-neighbor selection, tie handling, concordance calculation, and Murcko structural context.

Validation

  • Passed the complete test suite: 658 tests.
  • Confirmed git diff --check is clean after merging PR #26 into main.
  • Confirmed that MODELABILITY INDEX output-traceability changes do not alter the scientific calculation or fingerprint .npz export contract.

v0.14.0 - 2026-09-09

Added

  • Added canonical atom- and bond-aware Bemis-Murcko scaffold context to the MODELABILITY INDEX population.
  • Added Murcko population coverage for cyclic and acyclic structures, scaffold counts, shared-scaffold coverage, and scaffold-level activity-label organization metrics.
  • Added an adjusted scaffold-effect metric that accounts for the number of observed Murcko scaffold groups while preserving negative values when applicable.
  • Added nearest-neighbor diagnostics for exact similarity ties, tie-sensitive label concordance, and fingerprint-identical neighbors.
  • Added a Murcko nearest-neighbor interface that distinguishes cyclic and acyclic neighbor transitions and same-scaffold versus different-scaffold relationships.
  • Added a compact Structural context section to MODELABILITY INDEX results and Murcko scaffold provenance to Analysis details.

Changed

  • Integrated Murcko structural context as an interpretative layer around the existing MODELABILITY INDEX without changing its fingerprint-space calculation, nearest-neighbor selection rule, tie policy, or macro-average aggregation.
  • Preserved the existing MODELABILITY INDEX analysis identity and chemvault_analysis_hash; Murcko context is versioned independently through murcko_modelability_context/v1.
  • Updated completed-job reuse so legacy MODELABILITY INDEX results without the Murcko context contract are not restored as current analyses, while compatible persisted fingerprint artifacts remain reusable.
  • Preserved nested Murcko structural context across local and HTTP backend execution without introducing a separate API endpoint or result schema.
  • Kept legacy MODELABILITY INDEX results display-compatible when structural context is absent.

Validation

  • Passed the complete test suite: 656 tests.
  • Confirmed git diff --check is clean after merging PR #25 into main.
  • Confirmed Murcko structural context is preserved across FastAPI and BackendGateway execution paths.
  • Completed local Streamlit smoke validation with two real MODELABILITY INDEX datasets, confirming the Structural context summary, 3-by-2 metric layout, Murcko provenance, and compatibility with the existing result presentation.

v0.13.1 - 2026-07-31

Added

  • Expanded the curated UniProt organism catalog for strict single-target gene resolution.
  • Added support for:
  • Homo sapiens — Human — NCBI taxonomy ID 9606;
  • Mus musculus — Mouse — NCBI taxonomy ID 10090;
  • Rattus norvegicus — Rat — NCBI taxonomy ID 10116;
  • Oryctolagus cuniculus — Rabbit — NCBI taxonomy ID 9986;
  • Mesocricetus auratus — Golden hamster — NCBI taxonomy ID 10036.

Changed

  • Preserved Homo sapiens as the default organism while using an explicit, curated selector order independent of taxonomy-ID sorting.
  • Kept the organism catalog backend-driven and reusable by both local and HTTP execution modes.
  • Preserved the strict contract of one gene symbol and one organism resolving to exactly one reviewed UniProt accession.
  • Preserved direct UniProt-accession input and all downstream PubChem, Structured activity, HARMONSMILE, activity-label, Modelability Index, and fingerprint workflows.

Validation

  • Passed the complete test suite: 633 tests.
  • Passed 135 tests covering protein identifiers, FastAPI, API client, backend gateway, and the Streamlit target dialog.
  • Confirmed live reviewed UniProt resolution for all five supported organisms.
  • Confirmed visually that the selector preserves the curated order and keeps Homo sapiens selected by default.

v0.13.0 - 2026-07-29

Added

  • Added a strict single-target workflow that resolves one gene symbol and supported organism to exactly one reviewed UniProt accession before launching the existing PubChem protein-search pipeline.
  • Added UniProt target resolution through the application, backend gateway, HTTP client, and FastAPI layers, using exact primary gene-name and organism matching.
  • Added local and HTTP backend support for launching, querying, cancelling, and finalizing PubChem protein-search jobs.
  • Added durable target identity provenance containing the original input mode, canonical UniProt accession, gene symbol, organism, protein name, entry name, common name, taxonomy identifier, and reviewed status when available.
  • Added a Target identity section to the Database summary while preserving the existing active-table, PubChem assay-coverage, and activity-availability sections.

Changed

  • Routed the Streamlit PubChem target workflow through BackendGateway in both local-default and HTTP API-client modes.
  • Preserved the UniProt accession as the canonical operational identifier for PubChem retrieval and all downstream CHEMVAULT workflows.
  • Preserved direct UniProt-accession input alongside the new gene-symbol and organism workflow.
  • Restricted target resolution to one target per execution, without batch resolution, target panels, or multiple-protein launches.
  • Preserved PubChem extraction, Structured activity, HARMONSMILE, activity labels, Modelability Index, and fingerprint scientific contracts.
  • Kept legacy databases readable without inferring or silently backfilling missing target identity metadata.

Validation

  • Passed the complete test suite: 628 tests.
  • Completed local-default validation of gene-symbol resolution, PubChem job execution, target identity persistence, and Database summary rendering.
  • Completed HTTP API-client validation with LEPR and Homo sapiens taxonomy identifier 9606, resolving to reviewed UniProt accession P48357.
  • Confirmed PubChem job launch, polling, finalization, persisted provenance, and target identity retrieval through FastAPI.
  • Confirmed direct UniProt-accession compatibility and correct legacy-database presentation without inferred metadata or visible raw HTML.

v0.12.0 - 2026-07-27

Added

  • Added Modelability Index support for Morgan, Feature Morgan, Atom Pair, RDKit Topological, Topological Torsion, Layered, and MACCS fingerprints through MOLRAPTOR 0.4.1.
  • Added fingerprint selection to the Modelability Index card while preserving Morgan as the default representation.
  • Added fingerprint-specific Modelability job execution, result restoration, provenance display, persisted artifact reuse, and .npz export across local and HTTP backend modes.

Changed

  • Scoped Modelability analyses and visible results by database, source table, and fingerprint type, allowing multiple fingerprint representations to coexist without overwriting or restoring incompatible results.
  • Derived analysis identities, fingerprint artifact identities, representation profiles, vector sizes, and export metadata from the canonical MOLRAPTOR fingerprint configuration.
  • Preserved backward compatibility for existing Morgan analyses, legacy persisted jobs, backend gateway calls, and positional export consumers.
  • Moved shared Streamlit Session State keys from the project root into the ui presentation package.

Validation

  • Passed the complete test suite: 539 tests.
  • Completed local-default visual and manual validation with P21554 and P34971.
  • Confirmed fingerprint selection, job execution, result restoration, fingerprint-specific provenance, stale-result hiding, persisted artifact reuse, and .npz download behavior.
  • Confirmed correct application behavior and a consistent, satisfactory UI/UX across the manually tested workflows.

v0.11.4 - 2026-07-23

Changed

  • Expanded the Modelability Index population from reference-selected structures to all consolidated structures with valid binary Active or Inactive outcomes and a Reference_Selection_Status of either selected or no_eligible_activity.
  • Updated the Modelability population policy from reference_selected_only/v1 to consolidated_binary_outcomes/v1, ensuring incompatible persisted analyses and fingerprint artifacts are not reused.
  • Grouped table management and activity-record repair controls inside a bordered Database maintenance section.
  • Renamed the Advanced maintenance expander to Repair activity records.
  • Kept the Modelability Index result subcard visible for every active table, displaying a placeholder when no table-specific result is available.

Fixed

  • Fixed Modelability Index rejection of consolidated datasets whose Inactive structures had Reference_Selection_Status set to no_eligible_activity.
  • Added explicit rejection of blank or unsupported Reference_Selection_Status values before fingerprint encoding.
  • Fixed Modelability fingerprint .npz downloads for valid numbered consolidation outputs such as activity_subset_IC50_structure_consolidated_2.
  • Preserved the original consolidated table name for fingerprint artifact lookup and exported provenance while using the normalized activity token only for the existing filename contract.
  • Improved Modelability workflow discoverability by showing the result area before the first calculation and while switching between tables.

Validation

  • Passed the complete test suite: 523 tests.
  • Confirmed the corrected Q7Z2W7 IC50 population contains 630 unique structures: 563 Active and 67 Inactive.
  • Completed the Q7Z2W7 Modelability Index calculation with a result of approximately 0.969 and preserved the existing Morgan fingerprint, Tanimoto similarity, nearest-neighbor, and macro-average contracts.
  • Confirmed manually that fingerprint .npz download works for a numbered consolidated table.
  • Completed cold visual validation of the Database maintenance grouping and the persistent Modelability result placeholder for main, filtered activity, consolidated activity, and completed-result states.

v0.11.3 - 2026-07-23

Changed

  • Replaced PubChem compound-title retrieval through long GET URLs with POST form requests, while preserving the existing 500-CID batch size, response contract, retries, cancellation checks, and persistence flow.
  • Refined the ACTIVITY LABELS guidance for harmonized tables that do not satisfy the Structured activity eligibility requirements.
  • Preserved the existing scientific eligibility rules and structure- consolidation behavior.

Fixed

  • Fixed missing Compound_Name values when PubChem rejected compound-title GET requests containing large CID batches.
  • Replaced ambiguous eligibility guidance with the concise message: Select a Structured activity table after running SMILES HARMONIZED.

Validation

  • Passed the complete test suite: 518 tests.
  • Completed a cold PubChem workflow with 1,038 of 1,038 compound names recovered and no missing titles.
  • Retrieved the 1,038 compound titles in 1.542 seconds while keeping the complete workflow below seven minutes.
  • Confirmed manually that ineligible harmonized tables remain blocked from ACTIVITY LABELS without changing the scientific workflow.

v0.11.2 - 2026-07-22

Added

  • Added deterministic scientific identities for reusing compatible completed Modelability Index analyses after restarting CHEMVAULT.
  • Added persistent SQLite fingerprint artifacts containing the ordered MOLRAPTOR fingerprint matrix, representation profile, dependency versions, structure mapping, hashes, and integrity metadata.
  • Added self-contained Modelability fingerprint export in .npz format, including the fingerprint matrix, ordered harmonized SMILES, Active/Inactive outcomes, binary labels, stable structure identifiers, and canonical provenance metadata.
  • Added local and HTTP backend support for Modelability fingerprint downloads through the existing backend gateway.
  • Added the Download fingerprints (.npz) control beside the nearest-neighbor report download.
  • Added the filename contract <database_id>_<activity_type>_fingerprints_<analysis8>.npz, where analysis8 contains exactly the first eight characters of the complete analysis identity.

Changed

  • Restored compatible completed Modelability Index results from persisted job state when the source population and scientific contracts remain unchanged.
  • Reused valid persisted fingerprints without invoking MOLRAPTOR again.
  • Kept .npz generation transient and in memory; generated export files are not persisted by CHEMVAULT.
  • Updated the visible sidebar operation name from HARMONSMILE to SMILES HARMONIZED, while preserving HARMONSMILE attribution as the external calculation engine and retaining internal technical identifiers.
  • Updated README and FastAPI documentation for the current Modelability Index, structure-consolidation, scientific-runtime, and fingerprint-export paths.
  • Preserved the Modelability Index formula, Morgan fingerprint profile, nearest-neighbor method, and scientific result contract.

Fixed

  • Added lazy fingerprint-artifact backfill for compatible legacy Modelability analyses created before fingerprint persistence was introduced.
  • Prevented internal CHEMVAULT, SQLite, and support tables from appearing in user-facing table workflows.
  • Added visible download errors for missing, corrupt, incompatible, or stale fingerprint artifacts instead of silently hiding the failure.
  • Aligned the Modelability Index card title typography with the other sidebar workflow cards.

Validation

  • Passed the complete test suite: 517 tests.
  • Completed manual cold-start validation for restored analyses, legacy artifact backfill, repeated .npz downloads, stable eight-character filename hashes, and aligned download controls.

v0.11.1 - 2026-07-21

Changed

  • Updated the pinned MOLRAPTOR dependency from 0.2.0 to 0.3.0.
  • Confirmed compatibility of the existing Modelability Index workflow with MorganFingerprintProfile and encode_fingerprints from MOLRAPTOR 0.3.0.
  • Preserved the existing Morgan fingerprint profile, Modelability Index calculation, provenance contract, and user interface without scientific algorithm changes.

v0.11.0 - 2026-07-20

Added

  • Added the native CHEMVAULT Modelability Index workflow for evaluating nearest-neighbor class concordance in consolidated Active/Inactive structure datasets.
  • Added strict input eligibility for activity_subset_XX_structure_consolidated tables containing SMILES_Harmonized, Outcome, and Reference_Selection_Status.
  • Added exclusion of rows whose Reference_Selection_Status is not selected, while preserving the original PubChem Active and Inactive labels without introducing activity-threshold rules.
  • Added in-memory Morgan fingerprint encoding through MOLRAPTOR 0.2.0. CHEMVAULT consumes the returned fingerprints but does not implement a separate fingerprint-generation engine.
  • Added a reproducible molecular representation profile using 2048-bit Morgan fingerprints with radius 2, RDKit default invariants, bond types and ring membership, and no chirality or redundant environments.
  • Added deterministic single-nearest-neighbor assignment using Tanimoto similarity and stable ordered-index tie resolution.
  • Added calculation of the Modelability Index, Active Concordance, and Inactive Concordance using macro-averaged class concordance.
  • Added a complete structure-level nearest-neighbor report for inspection and downstream analysis.
  • Added persisted fingerprint-profile and analysis provenance, with concise scientific parameters exposed through the end-user interface.
  • Added local and HTTP backend-job execution through the existing CHEMVAULT backend gateway.
  • Added table-specific Streamlit result state so switching tables does not misattribute stored Modelability Index results.
  • Added the MODELABILITY INDEX execution card and a result card aligned with the existing CHEMVAULT interface.
  • Preserved CURRENT_TABLE during Modelability Index execution.

Modelability Index method

CHEMVAULT evaluates only rows satisfying:

[ \operatorname{Reference_Selection_Status}(r) = \texttt{selected} ]

with a usable SMILES_Harmonized and a binary Outcome equal to Active or Inactive.

For every eligible structure (i), MOLRAPTOR generates an in-memory binary Morgan fingerprint (F_i). CHEMVAULT calculates pairwise Tanimoto similarity:

[ T(F_i,F_j) = \frac{ \left|F_i \cap F_j\right| }{ \left|F_i\right| + \left|F_j\right| - \left|F_i \cap F_j\right| } ]

The nearest neighbor of structure (i) is:

[ j^{}(i) = \operatorname T(F_i,F_j) ]}_{j \ne i

When multiple structures have the same maximum similarity, CHEMVAULT applies the stable ordered-input index as a deterministic technical tie-breaker.

Nearest-neighbor concordance for structure (i) is:

[ c_i = \begin{cases} 1, & \operatorname{Outcome}(i) = \operatorname{Outcome}(j^{*}(i)) \ 0, & \text{otherwise} \end{cases} ]

The class-specific concordances are:

[ C_{\mathrm{Active}} = \frac{1}{N_{\mathrm{Active}}} \sum_{i:\,y_i=\mathrm{Active}} c_i ]

and:

[ C_{\mathrm{Inactive}} = \frac{1}{N_{\mathrm{Inactive}}} \sum_{i:\,y_i=\mathrm{Inactive}} c_i ]

The Modelability Index is their macro average:

[ \operatorname{Modelability\ Index} = \frac{ C_{\mathrm{Active}} + C_{\mathrm{Inactive}} }{2} ]

This macro averaging gives equal weight to the Active and Inactive classes regardless of class imbalance. Values closer to 1 indicate stronger local same-class nearest-neighbor concordance for the selected molecular representation profile.


v0.10.5 - 2026-07-15

Added

  • Added the post-HARMONSMILE Activity Labels workflow for creating a traceable derived table grouped by SMILES_Harmonized.
  • Added one-row-per-structure consolidation when all usable observations for the same harmonized structure have a consistent Active or Inactive outcome.
  • Added traceable exclusion of structures with conflicting Active/Inactive labels, unsupported non-binary outcomes, or unusable harmonized structures.
  • Added deterministic, activity-based selection of Reference_CID and Reference_AID using eligible exact activity measurements converted to micromolar.
  • Added reference-activity fields, source CID/AID provenance, source-row counts, distinct assay counts, and retained HARMONSMILE molecular columns to the consolidated output.
  • Added persistent consolidation metadata covering source rows, exclusions, final structures, represented observations, reference-selection results, and Active/Inactive evidence by source assays.
  • Added local and HTTP backend support for Activity Labels execution and retrieval of its persisted summary through the backend gateway.

Activity-label consolidation method

For each usable harmonized structure (s), CHEMVAULT forms the group:

[ G_s = \left{ r \;:\; \operatorname{SMILES_Harmonized}(r)=s \right} ]

The set of normalized outcomes observed for that structure is:

[ L_s = \left{ \operatorname{Outcome}(r) \;:\; r \in G_s \right} ]

The structure is retained only when all usable observations agree on one binary label:

[ L_s = {\mathrm{Active}} ]

or:

[ L_s = {\mathrm{Inactive}} ]

A structure is excluded when:

[ {\mathrm{Active},\mathrm{Inactive}} \subseteq L_s ]

or when the group contains only unsupported non-binary outcomes, lacks a usable SMILES_Harmonized, or has an unusable HARMONSMILE result.

For every retained structure, CHEMVAULT evaluates its source activity observations. An activity observation is eligible for reference selection only when:

  • Relation is blank or =;
  • Activity_Value is finite and greater than zero;
  • Unit is supported and convertible to micromolar;
  • Activity_Type matches the single non-empty activity type of the source table.

Explicitly censored values such as <, <=, > and >= are preserved in the source evidence but are not treated as exact measurements in the reference calculation.

Let the eligible exact activities, converted to micromolar, be:

[ x_1,x_2,\ldots,x_n \qquad x_i > 0 ]

CHEMVAULT calculates the geometric mean activity:

[ g = \exp\left( \frac{1}{n} \sum_{i=1}^{n} \ln x_i \right) ]

Each eligible observation is compared with this geometric mean using logarithmic distance:

[ d_i = \left| \ln x_i-\ln g \right| ]

The reference observation is selected as:

[ i^{} = \operatorname \left| \ln x_i-\ln g \right| ]}_{i

Reference_CID, Reference_AID, Reference_Activity_Type, Reference_Relation, Reference_Activity_Value, Reference_Activity_Value_Raw, Reference_Unit, and Reference_Activity_Value_uM are all taken from the same selected source observation (i^{*}).

If two or more eligible observations have exactly the same logarithmic distance, CHEMVAULT applies a stable ordering of CID, AID, and source-row values only as a technical tie-breaker.

The procedure is deterministic because the same eligible source observations produce:

  1. the same geometric mean (g);
  2. the same logarithmic distances (d_i);
  3. the same minimum-distance candidates;
  4. the same tie-broken reference, independently of the original row order.

If a retained structure has no eligible exact activity observation, the structure remains in the consolidated table because its binary outcome is still consistent, but its reference fields remain empty and Reference_Selection_Status is set to no_eligible_activity.

Changed

  • Renamed the former representative identifiers to Reference_CID and Reference_AID to avoid implying unsupported scientific superiority.
  • Replaced arbitrary minimum-CID reference selection with the deterministic geometric-mean and minimum-log-distance method described above.
  • Added a persistent Activity labels summary to Table Manager, including:
  • source-row and usable-structure counts;
  • unusable-row and label-conflict exclusions;
  • final Active and Inactive structure counts;
  • represented source observations;
  • additional observations consolidated;
  • selected and unavailable activity references;
  • distinct source assays and source observations for each binary outcome.
  • Prevented recursive Activity Labels execution on a table that already contains consolidated activity labels.
  • Improved the Database summary by separating:
  • active-table information;
  • PubChem assay coverage;
  • activity-data availability.
  • Replaced legacy-oriented and implementation-oriented labels with clearer end-user terminology.
  • Moved Structured activity recovery into a collapsed Advanced maintenance section and clarified its purpose without changing its recovery behavior.
  • Improved UI consistency through reusable summary-section renderers, responsive metric layouts, uniform spacing, safe HTML rendering, and controlled local error presentation.
  • Preserved equivalent behavior between local and API-client modes without introducing silent HTTP-to-local fallback.

Notes

  • The original HARMONSMILE-enriched source table remains unchanged.
  • The consolidated table contains one retained row per usable SMILES_Harmonized.
  • Structures with contradictory Active/Inactive evidence are excluded from the derived binary table but remain preserved in the original source table.
  • Additional source observations are consolidated traceably through Source_CIDs, Source_AIDs, Source_Row_Count, and Source_AID_Count.
  • CHEMVAULT does not calculate molecular fingerprints in this workflow.
  • CHEMVAULT does not train machine-learning models in this workflow.
  • CHEMVAULT does not apply activity thresholds or transform measurements to pEC50 or pKi.
  • Activity values are used only to select a traceable source reference within each retained structure group.

v0.10.4 - 2026-07-13

Added

  • Added explicit per-database scientific runtime activation through the local and HTTP backend gateways.
  • Added automatic recovery of interrupted HARMONSMILE jobs using the persisted SQLite job state and successful cache checkpoints.
  • Added visible notification when an interrupted HARMONSMILE job is recovered for the selected database.

Changed

  • Made HARMONSMILE submission non-blocking in Streamlit.
  • Replaced the long in-command polling loop with periodic persisted-status refresh using Streamlit fragments.
  • Scoped scientific-job recovery to the explicitly selected database instead of scanning every database at application startup.
  • Isolated temporary HARMONSMILE input files per invocation.

Fixed

  • Fixed valid long-running HARMONSMILE jobs being reported as failed after the previous 30-minute monitoring window.
  • Prevented equivalent pending or running HARMONSMILE jobs from being launched more than once.
  • Prevented unselected databases from being opened, migrated, locked, or recovered merely because Streamlit or FastAPI started.
  • Preserved the original job ID and reused committed HARMONSMILE cache chunks when recovering interrupted work.

Notes

  • HARMONSMILE chemistry, dependency version, and SQLite cache schema are unchanged.
  • CHAMANP and PubChem execution remain outside the scientific-job recovery scope of this release.

Validation

  • Full suite passed on main: 385 passed.
  • git diff --check passed.
  • Manual local-mode validation completed a 3,293-row HARMONSMILE workflow in approximately 32 minutes, beyond the previous monitoring limit.
  • The run processed 2,319 unique CIDs and merged the expected HARMONSMILE columns into all 3,293 target rows.
  • Same-job recovery, cache checkpoint reuse, duplicate prevention, per-database isolation, and non-blocking monitoring were covered by automated tests.

v0.10.3 - 2026-07-12

Changed

  • Refined the Streamlit table and curation workflow layout.
  • Grouped Curate actions into clearer HARMONSMILE and CHAMANP workflow cards.
  • Reduced Structured activity previews and improved the Structured activity filter flow.
  • Added filtered Structured activity table creation from explicit activity filters.
  • Kept activity subset tables as full filtered Structured activity tables, preserving activity columns instead of reducing them to CID-only inputs.
  • Clarified manual structured activity backfill as a maintenance/recovery action.
  • Reordered table workflow sections and removed redundant active-schema display.

v0.10.2 - 2026-07-09

Changed

  • Updated CHEMVAULT to harmonsmile==0.3.2.
  • Removed the v0.10.1 CSV empty-delimiter workaround for HARMONSMILE input.
  • Restored simple CSV-based HARMONSMILE input using a safe CID column.
  • Relied on HARMONSMILE 0.3.2 deterministic CSV loading, robust CID aliases, and canonical PubChem_CID output.
  • Updated HARMONSMILE job-contract documentation and focused integration tests for the 0.3.2 contract.

Notes

  • This release does not change the scientific backend job contract.
  • CHAMANP backend execution and PubChem API execution/cancellation remain outside this release.

Validation

  • Full suite passed on main: 346 passed.
  • HARMONSMILE 0.3.2 was verified in chemvault_env.
  • Architectural grep over api, application, and services for Streamlit/session-state references returned no matches.

v0.10.1 - 2026-07-09

Fixed

  • Fixed a HARMONSMILE 0.3.1 input-column regression where the temporary one-column CSV header PubChem CID could be parsed as separate PubChem and CID columns.
  • Preserved CSV as the temporary HARMONSMILE interchange format while using a safe CID input column and normalizing returned CID data back to PubChem_CID.
  • Ensured HARMONSMILE execution works from Streamlit when the selected source column is named CID.

Validation

  • Full suite passed on main: 346 passed.
  • Architectural grep over api, application, and services for Streamlit/session-state references returned no matches.
  • Manual Streamlit validation passed on Dev10_P34971 / harmin: HARMONSMILE ran and created the expected output columns.

v0.10.0 - 2026-07-09

Added

  • Added a generic scientific backend job boundary for reusable workflow execution.
  • Added application/scientific_jobs.py to register, create, execute, and inspect scientific jobs by job type.
  • Added generic backend gateway and API-client methods for launching and querying scientific jobs.
  • Added HARMONSMILE 0.3.1 integration coverage, including status/message/result column handling.

Changed

  • Consolidated the v0.9.0 HARMONSMILE backend job path into a reusable scientific job contract.
  • Made GET /databases/{database_id}/jobs/{job_id} job-type-neutral instead of depending on HARMONSMILE-specific status lookup.
  • Aligned local and API HARMONSMILE execution around the same launch, poll, and terminal-status lifecycle.
  • Separated backend transport failures from persisted workflow failures.
  • Replaced PubChem-specific stale-job wording with generic backend-job wording.
  • Updated CHEMVAULT’s HARMONSMILE dependency from harmonsmile==0.2.4 to harmonsmile==0.3.1.
  • Updated API and job-contract documentation to describe the current scientific backend job contract.

Notes

  • HARMONSMILE remains the only scientific workflow exposed through the backend job contract in this release.
  • CHAMANP backend execution, PubChem API execution, PubChem cancellation, remote workers, task queues, Docker, auth, deployment, and frontend replacement remain outside this release.
  • ARCHITECTURE.md remains an internal untracked file and is not part of this release commit.

Validation

  • Full suite passed on main: 346 passed.
  • Architectural grep over api, application, and services for Streamlit/session-state references returned no matches.
  • HARMONSMILE 0.3.1 was verified in chemvault_env.

v0.9.0 - 2026-07-06

Added

  • Added HARMONSMILE backend job execution through the backend gateway.
  • Added POST /databases/{database_id}/jobs/harmonsmile to launch HARMONSMILE backend jobs.
  • Added GET /databases/{database_id}/jobs/{job_id} to inspect HARMONSMILE job status.
  • Added a minimal backend job runtime for asynchronous HARMONSMILE API execution.
  • Added Streamlit polling for HARMONSMILE job progress and terminal status.

Changed

  • Extended the backend gateway from read-only/export coverage to real scientific workflow execution.
  • Routed Streamlit HARMONSMILE execution through the backend gateway.
  • Preserved local mode as the default execution path.
  • Preserved API mode without silent local fallback when CHEMVAULT_API_URL is configured.
  • Replaced long blocking HARMONSMILE API execution with quick launch plus status polling.
  • Improved HARMONSMILE UI execution state handling for success, failure, backend connection loss, and stale workflow state.

Notes

  • This release is the first backend execution milestone for CHEMVAULT.
  • Scope is limited to HARMONSMILE execution.
  • PubChem execution, PubChem cancellation, CHAMANP execution, remote workers, auth, Docker, deployment, and frontend replacement remain outside this release.
  • Level 2 is advanced but not yet complete.

Validation

  • Full suite passed on main: 344 passed.
  • Manual API-mode validation passed for normal HARMONSMILE execution and FastAPI shutdown during polling.

v0.8.0 - 2026-07-03

Added

  • Added read-only operation history/provenance access through the backend gateway.
  • Added GET /databases/{database_id}/operations for read-only operation history retrieval.
  • Added current table CSV export through the backend gateway.
  • Added GET /databases/{database_id}/tables/{table_name}/export?columns=... for CSV export of the current table.
  • Added a typed backend job status contract for future long-running backend execution.

Changed

  • Extended Streamlit backend-gateway coverage to include operation history/provenance and current table CSV export.
  • Clarified README usage for default local mode and optional API-client mode.
  • Documented how CHEMVAULT_API_URL selects API-client mode and how to return to local mode.
  • Updated API documentation to describe the new operation-history and CSV-export endpoints.
  • Documented that job runtime endpoints, workers, cancellation endpoints, and execution migration remain deferred.

Notes

  • This release further consolidates the Streamlit-to-backend boundary for read-only operations and CSV export.
  • Scope remains limited to read-only inspection/export and backend contract preparation.
  • PubChem execution, HARMONSMILE execution, CHAMANP execution, structured activity export, subgroup export, runtime job endpoints, workers, cancellation mutation endpoints, curation writes, table mutations, auth, deployment, Docker, and frontend replacement remain outside this release.
  • The typed job status contract prepares future backend job execution without changing current runtime behavior.

Validation

  • Full suite passed on main: 325 passed in 22.53s.

v0.7.0 - 2026-07-03

Added

  • Added ReadOnlyBackendGateway as a unified backend boundary for Streamlit read-only database exploration.
  • Added local and HTTP backend paths behind the gateway: Streamlit UI → ReadOnlyBackendGateway → local application/services or, when CHEMVAULT_API_URL is configured: Streamlit UI → ReadOnlyBackendGateway → HTTP client → FastAPI → application/services.
  • Added active table schema inspection through the read-only backend gateway.
  • Extended the existing table metadata API response with schema information.

Changed

  • Routed Streamlit read-only table listing, metadata, metrics, preview, and active table schema inspection through the backend gateway.
  • Concentrated runtime CHEMVAULT_API_URL backend selection inside clients/backend_gateway.py.
  • Preserved local mode as the default when CHEMVAULT_API_URL is not configured.
  • Preserved visible API-mode failures without silent local fallback when CHEMVAULT_API_URL is configured.
  • Updated API documentation to describe the unified read-only backend boundary.

Notes

  • Scope remains read-only.
  • PubChem execution, HARMONSMILE execution, CHAMANP execution, jobs/workers, curation writes, table mutations, auth, deployment, Docker, and frontend replacement remain outside this release.
  • This release does not complete the full Streamlit-to-FastAPI migration, but establishes the backend boundary required to continue that migration without scattered UI-level backend decisions.

Validation

  • Full suite passed on main: 300 passed in 22.60s.

v0.6.0 - 2026-07-03

Added

  • Expanded the Streamlit API-client mode for read-only database exploration when CHEMVAULT_API_URL is configured.
  • Routed database table listing through FastAPI GET /databases/{database_id}/tables.
  • Routed table metadata and headers through FastAPI GET /databases/{database_id}/tables/{table_name}/metadata.
  • Routed database row/group metrics through FastAPI GET /databases/{database_id}/tables/{table_name}/metrics.
  • Kept selected columns preview routed through FastAPI GET /databases/{database_id}/tables/{table_name}/preview.

Changed

  • Streamlit now has a broader read-only API-client path: Streamlit → API client → FastAPI → application/services.
  • Local Streamlit behavior remains the default when CHEMVAULT_API_URL is not configured.
  • API-mode failures are surfaced visibly instead of silently falling back when API mode is explicitly enabled.
  • Updated API documentation to describe the expanded read-only coverage.

Notes

  • Scope remains read-only.
  • PubChem execution, HARMONSMILE execution, jobs/workers, curation writes, exports, table mutations, auth, deployment, and frontend replacement remain outside this release.
  • This release advances the Streamlit-to-FastAPI decoupling path, but FastAPI is not yet a complete backend replacement.

0.5.0 - 2026-07-02

Added

  • Added an internal FastAPI read-only client.
  • Added an opt-in Streamlit API-client pilot using CHEMVAULT_API_URL.

Changed

  • Routed Columns → Selected columns preview through the FastAPI client when CHEMVAULT_API_URL is configured.
  • Preserved default local Streamlit behavior when CHEMVAULT_API_URL is not set.
  • Documented the dual FastAPI + Streamlit API-client mode in docs/api.md.
  • Clarified the README release checkout and existing-clone update workflow.

Notes

  • Scope remains limited: no PubChem execution through FastAPI, HARMONSMILE execution through FastAPI, workers, backend runner, export endpoints, or table mutation.

0.4.1 - 2026-07-02

Added

  • Added OpenAPI contract tests for the read-only API surface.
  • Added uvicorn==0.49.0 as the ASGI server dependency for local FastAPI execution.
  • Added read-only table metadata endpoint GET /databases/{database_id}/tables/{table_name}/metadata.

Changed

  • Documented FastAPI read-only API local execution.
  • Documented current API endpoints, limitations, and the metadata endpoint.

Notes

  • Scope remains read-only: no PubChem execution, workers, backend runner, or table mutation.

0.4.0 - 2026-07-01

Added

  • Added a minimal read-only FastAPI interface under api/.
  • Added GET /health.
  • Added GET /databases/{database_id}/tables.
  • Added GET /databases/{database_id}/tables/{table_name}/metrics.
  • Added GET /databases/{database_id}/tables/{table_name}/preview.
  • Added FastAPI TestClient coverage for health, table listing, metrics, preview, missing databases, missing tables, and invalid column requests.

Changed

  • Extended application/database_use_cases.py with backend/API-ready read-only helpers for database table listing, table state validation, table metrics, and invalid-column handling.
  • Added FastAPI/runtime test dependencies to requirements.txt.

Notes

  • FastAPI consumes application/; it does not depend on Streamlit or st.session_state.
  • Streamlit remains the local UI.
  • PubChem API endpoints, authentication, Docker, deployment, and remote workers remain intentionally out of scope for this checkpoint.

0.3.0 - 2026-07-01

Added

  • Added backend-ready application/ use-case layer.
  • Added database use cases for database creation, opening, refresh, and metrics.
  • Added table use cases for active column selection, previews, selected-row loading, and CSV export.
  • Added curation use cases for CID validation, HARMONSMILE, CHAMANP, and curated-data merge operations.

Changed

  • Updated Streamlit UI modules to delegate selected operations through application/.
  • Preserved Streamlit as the UI layer while keeping backend-ready orchestration outside the UI.

Validation

  • Full grep over application/ and services/ for Streamlit/session_state references returns no output.
  • Full test suite passed: 249 tests.
  • Manual Streamlit smoke test passed.

0.2.0 - 2026-07-01

Changed

  • Decoupled service-layer logic from Streamlit session state.
  • Refactored export, selection, curation, builders, and database services to receive explicit inputs and return explicit results/state.
  • Moved Streamlit session-state mutation, toast messages, and UI feedback responsibility to the UI layer.
  • Added DatabaseState to represent database-related UI state transitions without mutating Streamlit state inside services.

Validation

  • Full grep over services/ for Streamlit/session_state references returns no output.
  • Full test suite passed: 235 tests.
  • Manual Streamlit smoke test passed with existing and new databases.

0.1.0 - 2026-07-01

First formal tagged release of CHEMVAULT as a local Streamlit + SQLite application.

Added

  • Streamlit-based local interface for building, refining, curating, inspecting, and exporting molecular SQLite datasets.
  • CSV upload and CSV export workflows.
  • PubChem protein-target search using UniProt accessions and BioAssay-derived CIDs.
  • Persistent local PubChem worker jobs with a progress modal, job status, stage, progress, messages, and safe cancellation.
  • SQLite job persistence for PubChem searches.
  • main, compound_assays, and compound_activities tables for molecule, assay-link, and structured activity data.
  • HARMONSMILE integration for CID-based molecular property and SMILES enrichment.
  • CHAMANP workflow integration.
  • Structured activity filtering and CSV export.
  • Table Manager for inspecting tables, schema, provenance, and operation history, with derived-table deletion.
  • Local stable validation checklist in the README.

Changed

  • PubChem protein searches now use the local worker path instead of direct synchronous UI execution.
  • PubChem job lifecycle and launch logic are routed through a reusable service layer.
  • PubChem job state is exposed through a stable job-view contract instead of UI code depending on internal job-store records.
  • SQLite connection handling now includes a Streamlit-independent database core for backend services.
  • README documentation reflects the current local stable app and English UI labels.

Fixed

  • Stale PubChem worker jobs are detected and marked failed.
  • Locked PubChem job databases are treated as transient while the worker finishes writing.
  • Cancelled PubChem jobs are not registered as completed.
  • PubChem cancellation is checked during compound-name retry waits.
  • Release-noise debug prints were removed from normal Streamlit flows.

Validation

  • Full suite passed with python -m pytest -q -p no:cacheprovider.
  • Integration validation passed for:
    • P34971 complete PubChem smoke test.
    • P32245 cancellation smoke test.
    • Opening existing SQLite databases.
    • CSV export.
    • Structured activity filtering and export.