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
NULLstrings, 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
chemvaultconsole command that supports--helpand--versionand launches the installed Streamlit application without changing the caller's working directory. - Added a dedicated
Operation historyUI 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
Aboutsidebar 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.cffwith standardized software citation metadata, including authors, title, version, and repository information.
Changed¶
- Made
pyproject.tomlauthoritative for project metadata and runtime dependencies, and consolidated pytest discovery plus Ruff and mypy settings there; the redundantrequirements.txtandpytest.inifiles 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/toservices/harmonsmile_ingest.pyand 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+Cinterruption 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_widtharguments with the equivalentwidth="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.pycompatibility adapter and standalonetools/db_audit.pyCLI 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 checkcomplete without findings or broken requirements. - Confirmed the GitHub Actions CI run for commit
0f5a4e9completed 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 historywhile 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_assaysmaterialization 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_attemptedfor 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 incompound_assaysfrom satisfying the current-run completeness contract.
Validation¶
- Passed the complete test suite: 714 tests.
- Confirmed
git diff --checkreports 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
CIDfield 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 --checkis clean after merging PR #30 intomain. - 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 correspondingactivity_subset_Kirows 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_assaysand 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 --checkis 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 fromtoSource 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 --checkis clean after merging PR #28 intomain. - 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/v1andmurcko_modelability_context/v1contracts.
Validation¶
- Passed the complete test suite: 660 tests.
- Confirmed
git diff --checkis clean after merging PR #27 intomain. - 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_hashis 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, andpopulation_identityso 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
.npzcontract 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 --checkis clean after merging PR #26 intomain. - Confirmed that MODELABILITY INDEX output-traceability changes do not alter the
scientific calculation or fingerprint
.npzexport 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 throughmurcko_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 --checkis clean after merging PR #25 intomain. - 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 ID9606;Mus musculus— Mouse — NCBI taxonomy ID10090;Rattus norvegicus— Rat — NCBI taxonomy ID10116;Oryctolagus cuniculus— Rabbit — NCBI taxonomy ID9986;Mesocricetus auratus— Golden hamster — NCBI taxonomy ID10036.
Changed¶
- Preserved
Homo sapiensas 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 sapiensselected 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 identitysection 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
BackendGatewayin 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
LEPRand Homo sapiens taxonomy identifier9606, resolving to reviewed UniProt accessionP48357. - 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
.npzexport 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
uipresentation 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
.npzdownload 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
ActiveorInactiveoutcomes and aReference_Selection_Statusof eitherselectedorno_eligible_activity. - Updated the Modelability population policy from
reference_selected_only/v1toconsolidated_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 maintenancesection. - Renamed the
Advanced maintenanceexpander toRepair activity records. - Kept the
Modelability Index resultsubcard visible for every active table, displaying a placeholder when no table-specific result is available.
Fixed¶
- Fixed Modelability Index rejection of consolidated datasets whose
Inactivestructures hadReference_Selection_Statusset tono_eligible_activity. - Added explicit rejection of blank or unsupported
Reference_Selection_Statusvalues before fingerprint encoding. - Fixed Modelability fingerprint
.npzdownloads for valid numbered consolidation outputs such asactivity_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
.npzdownload works for a numbered consolidated table. - Completed cold visual validation of the
Database maintenancegrouping and the persistent Modelability result placeholder formain, 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 LABELSguidance 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_Namevalues 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 LABELSwithout 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
.npzformat, 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, whereanalysis8contains 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
.npzgeneration transient and in memory; generated export files are not persisted by CHEMVAULT. - Updated the visible sidebar operation name from
HARMONSMILEtoSMILES 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
.npzdownloads, 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
MorganFingerprintProfileandencode_fingerprintsfrom 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_consolidatedtables containingSMILES_Harmonized,Outcome, andReference_Selection_Status. - Added exclusion of rows whose
Reference_Selection_Statusis notselected, while preserving the original PubChemActiveandInactivelabels 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 INDEXexecution card and a result card aligned with the existing CHEMVAULT interface. - Preserved
CURRENT_TABLEduring 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
ActiveorInactiveoutcome. - 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_CIDandReference_AIDusing 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:
Relationis blank or=;Activity_Valueis finite and greater than zero;Unitis supported and convertible to micromolar;Activity_Typematches 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:
- the same geometric mean (g);
- the same logarithmic distances (d_i);
- the same minimum-distance candidates;
- 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_CIDandReference_AIDto 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, andSource_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 --checkpassed.- 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
CIDcolumn. - Relied on HARMONSMILE 0.3.2 deterministic CSV loading, robust CID aliases, and canonical
PubChem_CIDoutput. - 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, andservicesfor 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 CIDcould be parsed as separatePubChemandCIDcolumns. - Preserved CSV as the temporary HARMONSMILE interchange format while using a safe
CIDinput column and normalizing returned CID data back toPubChem_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, andservicesfor 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.pyto 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.4toharmonsmile==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.mdremains 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, andservicesfor 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/harmonsmileto 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_URLis 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}/operationsfor 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_URLselects 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
ReadOnlyBackendGatewayas a unified backend boundary for Streamlit read-only database exploration. - Added local and HTTP backend paths behind the gateway:
Streamlit UI → ReadOnlyBackendGateway → local application/servicesor, whenCHEMVAULT_API_URLis 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_URLbackend selection insideclients/backend_gateway.py. - Preserved local mode as the default when
CHEMVAULT_API_URLis not configured. - Preserved visible API-mode failures without silent local fallback when
CHEMVAULT_API_URLis 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_URLis 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_URLis 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_URLis configured. - Preserved default local Streamlit behavior when
CHEMVAULT_API_URLis 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.0as 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
TestClientcoverage for health, table listing, metrics, preview, missing databases, missing tables, and invalid column requests.
Changed¶
- Extended
application/database_use_cases.pywith 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 orst.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/andservices/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, andcompound_activitiestables 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:
P34971complete PubChem smoke test.P32245cancellation smoke test.- Opening existing SQLite databases.
- CSV export.
- Structured activity filtering and export.