Metadata-Version: 2.4
Name: grimace-py
Version: 0.1.18
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: POSIX :: Linux
Classifier: Typing :: Typed
Requires-Dist: rdkit>=2026.3
Requires-Dist: zstandard>=0.25
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Summary: Rust-first SMILES enumeration and next-token decoding with Python bindings.
Keywords: smiles,chemistry,rdkit,enumeration,decoding
Home-Page: https://github.com/numpde/grimace-py
License-Expression: PolyForm-Noncommercial-1.0.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/numpde/grimace-py
Project-URL: Issues, https://github.com/numpde/grimace-py/issues
Project-URL: Source, https://github.com/numpde/grimace-py

# grimace-py

`grimace-py` is a Rust-first RDKit add-on for exact rooted SMILES support
enumeration, online next-token decoding, seeded sampling, and reusable prepared
molecules. It provides:

- exact support enumeration for Grimace's supported writer language
- exact token inventories implied by that support
- legal next-token choices from a current SMILES prefix
- seeded legal samples with per-step token choices
- prepared molecule bytes for reuse without RDKit at read time

GRIMACE stands for "graph representation integrating multiple alternate
chemical equivalents", motivated by research on NMR spectroscopy with
language transformers ([link](https://numpde.github.io/shared/msc/)).

The public import name is `grimace`. Install the PyPI distribution named
`grimace-py`:

```bash
python -m pip install grimace-py
```

```python
import grimace
```

Plain `pip install grimace` installs an unrelated older package.

Repository: [github.com/numpde/grimace-py](https://github.com/numpde/grimace-py).

`grimace-py` is distributed under `PolyForm-Noncommercial-1.0.0`. Commercial
use is not permitted under the current license.

## Quick example

This example uses the currently supported runtime mode. See
[Runtime](docs/runtime.md) for flags and roots, and
[Limitations](docs/current-limitations.md) for scope and known gaps.

```python
from rdkit import Chem
import grimace

mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")

all_smiles = tuple(
    grimace.MolToSmilesEnum(
        mol,
        rootedAtAtom=-1,
        isomericSmiles=False,
        canonical=False,
        doRandom=True,
    )
)

assert len(all_smiles) == 304
```

## What to use

- Enumerate every supported string with `MolToSmilesEnum(...)`.
- Step through legal next tokens with `MolToSmilesDecoder(...)` or
  `MolToSmilesDeterminizedDecoder(...)`.
- Draw one seeded legal string with per-step token choices using
  `MolToSmilesSample(...)`.
- Diagnose rejected candidates with `MolToSmilesDeviation(...)`.
- Build dataset token coverage with `MolToSmilesTokenInventorySuperset(...)`.
- Reuse prepared molecules with `PrepareMol(...)` and `PreparedMol`.

## Documentation

Please find the main documentation at
[numpde.github.io/grimace-py](https://numpde.github.io/grimace-py/).

## Install

Package metadata declares Python `>=3.11` and `rdkit>=2026.3`. See
[Runtime](docs/runtime.md) for the exercised wheel and source-distribution
matrix.

For a host source build, you need Rust `>=1.83` and `maturin`:

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install maturin
maturin develop --release
```

## Development

Routine local checks are Docker-backed:

```bash
make checks
make ci
make test-package
make docs
make docs-serve
```

See [containerized development](docs/development/containerized.md) for the
lane contract.

## License

`grimace-py` is source-available under
[PolyForm Noncommercial 1.0.0](LICENSE). Third-party components remain under
their own licenses; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
Commercial use requires a separate commercial license from the author.

