API Reference

MOLRAPTOR exposes an intended public API through nine symbols. The project is pre-stable, so this API may change before 1.0. Internal modules are importable directly but are not part of the public contract.

from molraptor import MolraptorConfig
from molraptor import validate_config
from molraptor import run
from molraptor import DataValidator
from molraptor import MorganFingerprintProfile
from molraptor import FingerprintEncodingResult
from molraptor import FingerprintInputStatus
from molraptor import encode_fingerprints
from molraptor import __version__

---

In-memory Morgan fingerprinting

The in-memory API encodes an ordered sequence of SMILES without labels, paths, CSV files, MolraptorConfig, or other pipeline stages. It performs zero file I/O.

from molraptor import MorganFingerprintProfile, encode_fingerprints

profile = MorganFingerprintProfile(radius=2, fp_size=1024)
result = encode_fingerprints(["CCO", "not-a-smiles", "C(C)O"], profile)

fingerprints = result.fingerprints  # shape: (2, 1024), dtype: uint8
metadata = result.serialize_metadata()  # JSON-compatible; excludes the matrix

MorganFingerprintProfile records the complete effective Morgan bit-vector settings, including fixed defaults, and can be serialized with serialize(). The profile used for an encoding is also available in the result and covered by its deterministic profile hash.

encode_fingerprints preserves the order and duplicates of valid inputs. Valid molecules produce matrix rows; invalid or empty molecules produce no row and no zero-vector substitute. valid_indices maps matrix rows back to original input positions, while valid_count and invalid_count summarize the outcome.

FingerprintEncodingResult contains the uint8 matrix, effective profile, input statuses, shape and dtype, MOLRAPTOR and RDKit versions, and deterministic input/profile hashes. serialize_metadata() returns all of that metadata in a JSON-compatible dictionary while deliberately excluding the NumPy matrix.

FingerprintInputStatus records every original input_smiles and input_index. A valid status includes its fingerprint_index and rdkit_canonical_smiles; the latter is diagnostic metadata generated by RDKit and does not replace the caller's original SMILES. An invalid status instead has invalid_reason (parse_failure or empty_molecule) and no matrix index.

In-memory API versus file-based pipeline

The in-memory API intentionally supports partial valid results when some SMILES are invalid and never writes files. The existing run(config) pipeline executes fetch, curation, fingerprinting, and integrity validation and writes configured CSV/NPY artifacts. Its file-based fingerprint step is strict: if any SMILES is invalid, it reports the affected input row indices and writes no fingerprint or label artifacts.

MorganFingerprintProfile

Bases: BaseModel

Complete, serializable settings for a Morgan bit fingerprint.

All effective defaults are model fields, so regular Pydantic serialization retains them even when the caller constructs the profile with no arguments. The invariant policy is explicit and intentionally limited to RDKit's built-in Morgan atom and bond invariants in this schema version.

serialize()

Return the complete effective profile as JSON-compatible values.

encode_fingerprints

Encode an ordered sequence of SMILES as binary Morgan fingerprints.

Invalid and empty SMILES are represented only in input_statuses; they do not add rows to the fingerprint matrix. This function performs no file I/O and does not depend on pipeline configuration or labels.

FingerprintEncodingResult

In-memory fingerprints plus reproducibility and alignment metadata.

effective_profile property

Alias for the effective serialized profile used for encoding.

input_hash property

Short alias for :attr:ordered_input_hash.

serialize_metadata()

Return JSON-compatible result metadata without the NumPy matrix.

FingerprintInputStatus

Bases: BaseModel

Encoding status and row alignment for one original SMILES input.

original_index property

Alias emphasizing that input_index refers to the caller's input.

validate_status_contract()

Keep status-specific metadata complete and mutually exclusive.

---

MolraptorConfig

Bases: BaseModel

load(path) classmethod

Load, parse and validate a YAML config file.

---

validate_config

Validate a MOLRAPTOR runtime configuration object.

Parameters:

Name	Type	Description	Default
config	MolraptorConfig	Configuration to validate. When None, loads from examples/example_config.yaml.	None

Returns:

Type	Description
MolraptorConfig	The validated configuration object.

Raises:

Type	Description
ValueError	If one or more validation checks fail.

Examples:

>>> from molraptor import MolraptorConfig, validate_config
>>> config = MolraptorConfig.load("examples/example_config.yaml")
>>> validated = validate_config(config)

---

run

Validate and execute the full MOLRAPTOR pipeline.

Parameters:

Name	Type	Description	Default
config	MolraptorConfig	Runtime configuration. When None, loads from examples/example_config.yaml.	None

Raises:

Type	Description
ValueError	If configuration validation fails before execution begins.

Examples:

>>> from molraptor import MolraptorConfig, run
>>> config = MolraptorConfig.load("examples/example_config.yaml")
>>> run(config)

---

DataValidator

Static validation utilities.

---

Version

Package version metadata for MOLRAPTOR.

This module is the single source of truth for the project version. It is read by hatchling at build time via [tool.hatch.version] and imported by result_manager to stamp generated reports.