openclatura 0.1.0__tar.gz

openclatura-0.1.0/.dockerignore

@@ -0,0 +1,21 @@
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+.hypothesis
+build
+dist
+*.egg-info
+examples
+tests
+docs
+*.md
+!README.md

openclatura-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main, refactor_namer]
+  pull_request:
+    branches: ["**"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install "ruff==0.15.15"
+      - name: Ruff check
+        run: ruff check src/openclatura
+      - name: Ruff format check
+        run: ruff format --check src/openclatura
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Set up JDK (for OPSIN)
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run fast tests
+        run: |
+          pytest -m "not slow and not dataset and not golden" \
+                 --maxfail=20 \
+                 --durations=20
+
+  rdkit-compat:
+    # Strict golden-output regression across RDKit versions. Detects
+    # naming output that drifts with the RDKit upgrade cycle (aromaticity,
+    # kekulisation, H-count perception). Each matrix row pins a specific
+    # rdkit and runs only the `golden` test.
+    runs-on: ubuntu-latest
+    needs: [lint]
+    strategy:
+      fail-fast: false
+      matrix:
+        rdkit-version:
+          - "2024.03.6"
+          - "2024.09.6"
+          - "2025.03.6"
+          - "2025.09.5"
+          - "2026.3.2"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package + pinned rdkit
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install --force-reinstall --no-deps "rdkit==${{ matrix.rdkit-version }}"
+
+      - name: Show installed versions
+        run: |
+          python -c "import rdkit, sys; print('python', sys.version); print('rdkit', rdkit.__version__)"
+
+      - name: Run golden corpus test
+        run: pytest -m golden -v --no-header -rA
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: [lint]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Build image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: false
+          load: true
+          tags: openclatura:ci
+
+      - name: Smoke-test the image
+        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

openclatura-0.1.0/.github/workflows/docker-image.yml

@@ -0,0 +1,57 @@
+name: Build Docker image
+
+on:
+  push:
+    branches: [main, tests]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  IMAGE_NAME: ghcr.io/${{ github.repository }}
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build local image for smoke test
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          load: true
+          tags: openclatura:test
+
+      - name: Smoke test Docker image
+        run: |
+          docker run --rm -d -p 8000:8000 --name openclatura-test openclatura:test
+          sleep 5
+          curl --fail http://localhost:8000/healthz
+          docker stop openclatura-test
+
+      - name: Build and push image from main
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ env.IMAGE_NAME }}:main
+            ${{ env.IMAGE_NAME }}:${{ github.sha }}

openclatura-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Hatch
+.hatch/
+
+# Unit test / coverage / type checkers
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+.python-version
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Notebooks
+.ipynb_checkpoints/
+
+# Project-specific
+*.log
+*.jar
+opsin*.jar
+data/cache/
+.cache/
+
+# Docker
+.docker/

openclatura-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

openclatura-0.1.0/Dockerfile

@@ -0,0 +1,55 @@
+# syntax=docker/dockerfile:1.7
+
+# ----- builder stage -----------------------------------------------------
+FROM python:3.12-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /build
+
+# Build deps for rdkit wheels: typically just runtime; the manylinux wheels
+# carry their own libs. Keep this stage thin.
+RUN apt-get update -qq \
+ && apt-get install -y --no-install-recommends build-essential \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+# Install into a clean prefix so we can copy a slim layer into the runtime.
+RUN python -m pip install --upgrade pip \
+ && python -m pip install --prefix=/install ".[web,opsin]"
+
+
+# ----- runtime stage -----------------------------------------------------
+FROM python:3.12-slim AS runtime
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PATH="/usr/local/bin:${PATH}"
+
+# Java runtime for OPSIN round-trip verification (py2opsin shells out to java;
+# OPSIN itself requires Java >=8 so the newer JRE is fine).
+RUN apt-get update -qq \
+ && apt-get install -y --no-install-recommends \
+        default-jre-headless \
+        curl \
+        ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+# Bring in the installed package + deps from the builder stage.
+COPY --from=builder /install /usr/local
+
+# Non-root user.
+RUN useradd --create-home --shell /bin/bash openclatura
+USER openclatura
+WORKDIR /home/openclatura
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD curl -fsS http://127.0.0.1:8000/healthz || exit 1
+
+CMD ["python", "-m", "openclatura.web", "--host", "0.0.0.0", "--port", "8000"]

openclatura-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lamalab-org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openclatura-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: openclatura
+Version: 0.1.0
+Summary: Deterministic SMILES-to-IUPAC name generator based on the IUPAC Blue Book
+Project-URL: Homepage, https://github.com/lamalab-org/openclatura
+Project-URL: Repository, https://github.com/lamalab-org/openclatura
+Project-URL: Issues, https://github.com/lamalab-org/openclatura/issues
+Author: Adrian Mirza, Kevin Maik Jablonka, Rostislav Fedorov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chemistry,iupac,nomenclature,rdkit,smiles
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Requires-Dist: rdkit>=2023.09
+Provides-Extra: datasets
+Requires-Dist: datasets>=2.0; extra == 'datasets'
+Requires-Dist: huggingface-hub>=0.20; extra == 'datasets'
+Requires-Dist: pandas>=2.0; extra == 'datasets'
+Requires-Dist: tqdm>=4.65; extra == 'datasets'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6.92; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: py2opsin>=1.2; extra == 'dev'
+Requires-Dist: pydantic>=2.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff==0.15.15; extra == 'dev'
+Provides-Extra: opsin
+Requires-Dist: py2opsin>=1.2; extra == 'opsin'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: pydantic>=2.5; extra == 'web'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'web'
+Description-Content-Type: text/markdown
+
+# openclatura
+
+**Open Nomenclature Framework**
+
+`openclatura` is a deterministic SMILES-to-IUPAC name generator inspired by the IUPAC Blue Book 2013 recommendations.
+
+Built on top of RDKit, the package walks the molecular graph, detects functional groups and ring systems, selects the principal parent, assigns locants, and constructs the corresponding substitutive IUPAC name. Every step is recorded in an inspectable
+decision trace so the *why* of a name is recoverable, not just the *what*.
+
+> **Status:** alpha. The naming engine handles a broad slice of organic
+> structures (alkanes/alkenes/alkynes, common functional groups, simple
+> heterocycles, fused/spiro/bridged systems, retained names from the Blue
+> Book). PubChem/QM9/ZINC22 coverage is being measured; see `examples/`.
+
+## Install
+
+```bash
+pip install openclatura
+```
+
+Optional extras:
+
+| extra        | adds                                                  |
+| ------------ | ----------------------------------------------------- |
+| `[opsin]`    | `py2opsin` for OPSIN-based round-trip verification    |
+| `[datasets]` | `datasets` + `tqdm` for PubChem/QM9-style evaluations |
+| `[web]`      | FastAPI + uvicorn for the HTTP service                |
+| `[dev]`      | pytest, ruff, pre-commit, hypothesis, py2opsin        |
+
+```bash
+pip install "openclatura[opsin,datasets]"
+```
+
+## Quick start
+
+```python
+from openclatura import name_smiles
+
+name_smiles("CCO")          # 'ethanol'
+name_smiles("c1ccccc1")     # 'benzene'
+name_smiles("CC(=O)O")      # 'acetic acid'
+```
+
+### Typed result with rules hit + OPSIN round-trip
+
+For everything richer than the bare string, use `openclatura.name`:
+
+```python
+from openclatura import name
+
+result = name("CC(=O)Nc1ccccc1", include_trace=True, verify_opsin=True)
+
+result.name           # 'N-phenylacetamide'
+result.smiles         # 'CC(=O)Nc1ccccc1'
+result.ok             # True
+result.rules_hit      # ('P-44', 'P-45', 'P-41', 'P-61', 'P-67', ...)
+result.rule_hints     # ('Parent hydride / parent structure: Blue Book P-44 ...',)
+result.opsin_check.status   # 'matched' | 'mismatched' | 'skipped_no_java' | ...
+result.verified       # True when opsin_check is matched
+```
+
+Errors do not raise — they are captured on `result.error`, which makes
+the batch API safe to point at noisy datasets:
+
+```python
+from openclatura import name_many
+
+results = name_many(
+    ["CCO", "c1ccccc1", "definitely-not-a-smiles"],
+    processes="auto",       # or an integer, or 1 for in-process
+    verify_opsin=False,
+)
+[r.name for r in results if r.ok]
+```
+
+For the full decision trace (one `TraceStep` per phase: parse, perception,
+parent selection, numbering, assembly, …):
+
+```python
+from openclatura import analyze_smiles
+
+analysis = analyze_smiles("CC(=O)Nc1ccccc1")
+for step in analysis.decisions:
+    print(step.phase, step.decision, step.reason)
+```
+### CLI
+
+```bash
+openclatura name "CC(=O)Nc1ccccc1"            # → N-phenylacetamide
+openclatura name "CC(=O)Nc1ccccc1" --json     # JSON with trace + rules
+openclatura batch smiles.txt --output names.jsonl --processes auto
+```
+The CLI tool has OPSIN verification turned on by default. It can be turned off with
+
+```bash
+openclatura name "CN1C=NC2=C1C(=O)N(C(=O)N2C)C" --no-verify       
+```
+
+### Natural-language description (`describe`)
+
+`openclatura.describe(smiles)` walks the same trace and renders a
+deterministic, multi-paragraph explanation of how the name is built.
+Useful for explainability views and for generating (SMILES, name,
+description) training tuples:
+
+```python
+from openclatura import describe
+
+d = describe("CC(=O)Nc1ccccc1")
+print(d)            # multi-paragraph prose
+d.rules_hit         # ('P-44', 'P-45', 'P-41', 'P-61', 'P-67')
+d.components[0]     # DescribedComponent(phase='parse', text='RDKit parsed ...')
+```
+
+Same input → same output. No LLM in the loop.
+
+## Human-like description
+
+Openclatura can generate uncanny human-like descriptions of molecules.
+```python
+
+from openclatura import describe_human
+
+d = describe_human("CN1C=NC2=C1C(=O)N(C(=O)N2C)C")
+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 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). """
+
+```
+
+## Development
+
+```bash
+git clone https://github.com/lamalab-org/iupac-name-generator
+cd iupac-name-generator
+pip install -e ".[dev]"
+
+# run the unit + round-trip tests
+pytest
+
+# run only fast tests
+pytest -m "not slow and not dataset and not golden"
+
+# strict RDKit-version regression suite (also runs in the rdkit-compat CI job)
+pytest -m golden
+
+# lint and format
+ruff check --fix src/openclatura
+ruff format src/openclatura
+```
+
+Java is required for the OPSIN-based round-trip checks (see `py2opsin`).
+
+## HTTP service (Docker)
+
+The `[web]` extra ships a FastAPI app with `name`, `batch`, `describe`
+and `healthz` endpoints. The bundled `Dockerfile` includes a headless JRE
+so `verify_opsin=True` works out of the box.
+
+```bash
+# build + run
+docker build -t openclatura:local .
+docker run --rm -p 8000:8000 openclatura:local
+
+# or via compose
+docker compose -f docker/compose.yaml up --build
+```
+
+Call the API:
+
+```bash
+curl -X POST localhost:8000/name -H 'content-type: application/json' \
+     -d '{"smiles":"CC(=O)Nc1ccccc1","include_trace":true,"verify_opsin":true}'
+
+curl -X POST localhost:8000/batch -H 'content-type: application/json' \
+     -d '{"smiles":["CCO","c1ccccc1","CC(=O)O"],"processes":1}'
+
+curl -X POST localhost:8000/describe -H 'content-type: application/json' \
+     -d '{"smiles":"CC(=O)Nc1ccccc1"}'
+```
+
+OpenAPI docs are served at `http://localhost:8000/docs`.
+
+
+## License
+
+MIT. See `LICENSE`.