Merge pull request #36 from lamalab-org/tests

retianed names support for phenazine, phenanthrolines, acridine, carbazole, purine, indazole, xanthenes and their derivates

Author: r-fedorov

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [main, refactor_namer]
+    branches: [main, refactor_namer, tests]
   pull_request:
     branches: ["**"]
 
@@ -94,30 +94,65 @@ jobs:
         run: pytest -m golden -v --no-header -rA
 
   docker:
+    needs: [lint, test, rdkit-compat]
+    permissions:
+      contents: read
+      packages: write
+    uses: ./.github/workflows/docker-image.yml
+    secrets: inherit
+
+  paper-evaluations:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/tests'
+    needs: [lint, test, rdkit-compat]
     runs-on: ubuntu-latest
-    needs: [lint]
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      max-parallel: 3
+      matrix:
+        shard:
+          - qm9/qm9_all
+          - pubchem/pubchem_seed5_100000
+          - pubchem/pubchem_seed17_100000
+          - pubchem/pubchem_seed42_100000
+          - pubchem/pubchem_seed63_100000
+          - pubchem/pubchem_seed87_100000
+          - zinc22/zinc22_seed5_100000
+          - zinc22/zinc22_seed17_100000
+          - zinc22/zinc22_seed42_100000
+          - zinc22/zinc22_seed63_100000
+          - zinc22/zinc22_seed87_100000
+
     steps:
       - uses: actions/checkout@v4
 
-      - uses: docker/setup-buildx-action@v3
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
 
-      - name: Build image
-        uses: docker/build-push-action@v6
+      - name: Set up JDK for changed-name OPSIN checks
+        uses: actions/setup-java@v4
         with:
-          context: .
-          push: false
-          load: true
-          tags: openclatura:ci
+          distribution: temurin
+          java-version: "17"
+
+      - name: Install OpenClatura and regression dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
 
-      - name: Smoke-test the image
+      - name: Compare against the paper evaluation
         run: |
-          docker run -d --name openclatura-ci -p 8000:8000 openclatura:ci
-          for i in $(seq 1 30); do
-            if curl -fsS http://127.0.0.1:8000/healthz > /tmp/health.json; then
-              cat /tmp/health.json
-              exit 0
-            fi
-            sleep 2
-          done
-          docker logs openclatura-ci
-          exit 1
+          python evaluations/check_regression.py \
+            "evaluations/results/${{ matrix.shard }}_openclatura.jsonl" \
+            --processes auto \
+            --report "regression-reports/${{ strategy.job-index }}.json"
+
+      - name: Upload discrepancy report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: evaluation-regression-${{ strategy.job-index }}
+          path: regression-reports/*.json
+          if-no-files-found: error

.github/workflows/docker-image.yml

@@ -1,10 +1,7 @@
 name: Build Docker image
 
 on:
-  push:
-    branches: [main, tests]
-  pull_request:
-  workflow_dispatch:
+  workflow_call:
 
 permissions:
   contents: read
@@ -54,4 +51,4 @@ jobs:
           push: true
           tags: |
             ${{ env.IMAGE_NAME }}:main
-            ${{ env.IMAGE_NAME }}:${{ github.sha }}
+            ${{ env.IMAGE_NAME }}:${{ github.sha }}

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to openclatura
+
+Thank you for your interest in contributing to **openclatura**.
+
+openclatura aims to be a practical implementation of the **IUPAC Blue Book 2013** recommendations for organic nomenclature. This is the main scope of the project and the area we currently prioritize.
+
+We especially welcome:
+
+* bug reports
+* feature requests
+* tests
+* code contributions
+
+## Reporting unsupported or incorrect names
+
+Please open a GitHub issue if openclatura:
+
+* generates an incorrect name for a family of compounds
+* does not yet support a nomenclature feature.
+
+A useful issue includes:
+
+* input structures, preferably as SMILES
+* names generated by openclatura, or the error message
+* expected names
+* the suspected reason for the failure, if known
+* a reference or output from another program, such as OPSIN and a few related examples from the same family.
+
+For example, if one polycyclic structure fails, it is helpful to include a few similar polycyclic structures. This makes it easier to identify and implement the general missing rule instead of fixing only one molecule.
+
+## Feature requests
+
+Feature requests should also be submitted as GitHub issues.
+
+The current priority is nomenclature covered by the Blue Book 2013.
+
+## Contributing code
+
+Please open pull requests against the **`tests`** branch.
+
+Pull requests to this branch run the automated test and regression workflows. These checks help ensure that a change does not reduce the general naming performance or break previously supported cases.
+
+For code contributions, please:
+
+* add tests for new behavior or bug fixes;
+* include several related examples when implementing a general rule;
+* mention the relevant Blue Book rule or other reference when available; and
+* make sure the existing tests pass.
+
+We prioritize work that can be validated through **OPSIN** where possible. OPSIN validation is helpful for automated testing, but it is not the only measure of correctness, and valid cases that OPSIN does not support may still be considered.
+
+## Questions and discussions
+
+If you are unsure whether an example is a bug, a missing feature, or outside the current scope, please open an issue and describe what you found. 
+::: 

README.md

@@ -163,13 +163,12 @@ print(d.text)
 Processed SMILES: Cn1cnc2c1c(=O)n(C)c(=O)n2C
 Atom ids in that SMILES: C{0}n{1}1c{2}n{3}c{4}2c{5}1c{6}(=O{7})n{8}(C{13})c{9}(=O{10})n{11}2C{12}
 
-The molecule is named 2,4,7-trimethyl-2,4,7,9-tetraazabicyclo[4.3.0]nona-1(6),8-diene-3,5-dione.
+The molecule is named 1,3,7-trimethylpurine-2,6-dione.
 
-The molecule is built around a 9-membered bicyclic [4.3.0] heteroskeleton.
-Within that parent framework, there is nitrogen at positions 2 (atom id 11), 4 (atom id 8), 7 (atom id 1), and 9 (atom id 3).
-Within that parent framework, there is a double bond between position 1 (atom id 4) and position 6 (atom id 5) and a double bond between position 8 (atom id 2) and position 9 (atom id 3).
-The principal characteristic feature is oxo groups at positions 3 (atom id 9) and 5 (atom id 6).
-Attached to this framework are methyl groups at positions 2 (atom id 11), 4 (atom id 8), and 7 (atom id 1). """
+The molecule is built around the retained purine parent, 9-membered bicyclic [4.3.0] heteroskeleton.
+Within that parent framework, there is nitrogen at positions 1 (atom id 8), 3 (atom id 11), 7 (atom id 1), and 9 (atom id 3).
+The principal characteristic feature is oxo groups at positions 2 (atom id 9) and 6 (atom id 6).
+Attached to this framework are methyl groups at positions 1 (atom id 8), 3 (atom id 11), and 7 (atom id 1). """
 
 ```
 
@@ -231,6 +230,36 @@ OpenAPI docs are served at `http://localhost:8000/docs`.
 
 MIT. See `LICENSE`.
 
-## How to cite 
-Adrian Mirza, Kevin Maik Jablonka, Rostislav Fedorov. Openclatura–an Open-Source Nomenclature Framework for Rule-Based Molecule Naming. ChemRxiv. 15 July 2026.
-DOI: https://doi.org/10.26434/chemrxiv.15006114/v1
+## How to cite
+
+If you use Openclatura in your research, please cite the Openclatura preprint:
+
+```bibtex
+@article{openclatura2026,
+  author  = {Mirza, Adrian and Jablonka, Kevin Maik and Fedorov, Rostislav},
+  title   = {Openclatura--An Open-Source Nomenclature Framework for Rule-Based Molecule Naming},
+  journal = {ChemRxiv},
+  year    = {2026},
+  month   = jul,
+  day     = {15},
+  doi     = {10.26434/chemrxiv.15006114/v1},
+  url     = {https://doi.org/10.26434/chemrxiv.15006114/v1},
+  note    = {Preprint}
+}
+```
+
+If you are using OPSIN for verification, please cite the original OPSIN publication:
+
+```bibtex
+@article{lowe2011opsin,
+  author  = {Lowe, Daniel M. and Corbett, Peter T. and Murray-Rust, Peter and Glen, Robert C.},
+  title   = {Chemical Name to Structure: {OPSIN}, an Open Source Solution},
+  journal = {Journal of Chemical Information and Modeling},
+  year    = {2011},
+  volume  = {51},
+  number  = {3},
+  pages   = {739--753},
+  doi     = {10.1021/ci100384d},
+  url     = {https://doi.org/10.1021/ci100384d}
+}
+```