Library Reference

This page lists the current native workflow surface and the frozen pure-Python oracle used for differential testing.

Workflow

Adapter names are stable lowercase strings: aizynthfinder, askcos, directmultistep, dreamretroer, molbuilder, multistepttl, paroutes, retrochimera, retrostar, synllama, synplanner, syntheseus, and ursa.

Native Handles

NativePredictions exposes:

• write(path) to write JSON or JSON gzip from Rust
• to_dict() to create a Python snapshot
• json() to create a JSON string

score consumes the prediction payload. Later access through the old handle raises RuntimeError.

NativeEvaluation exposes the same materialization methods plus metric_label(). Analysis borrows the evaluation because its result is small.

Rust callers own Predictions, Evaluation, and AnalysisReport directly and use Serde for explicit serialization.

Core Models

The Python boundary represents individual models as JSON-compatible dictionaries. Corpus-sized prediction and evaluation collections remain native handles.

Producer Integration

These functions expose retrocast-core schema and provenance behavior to Python runners. They do not recreate the Rust models as Python classes.

Task files have an explicit trust boundary. Ordinary loads check the schema and constraint structure without repeating RDKit work. validate_task checks chemistry unless disabled, and write_task always verifies that every target SMILES is valid and produces the declared InChIKey.

Manifest creation requires every source and output file to exist. An output with content_type="unknown" can omit value, so large planner results are hashed from disk without a second Python-to-Rust serialization. Known content types require either value or an explicit content_hash. Lenient verification remains available only when requested for historical manifests.

Chemistry

No RDKit object crosses the Rust or Python API. Invalid chemical input raises ValueError in Python and returns EngineError in Rust.

Artifact I/O

task = retrocast.load_task("benchmark.json.gz")
payload = retrocast.read_json("results.json.gz")
retrocast.write_json_gz(payload, "results-copy.json.gz")

predictions.write("candidates.json.gz")
evaluation.write("evaluation.json.gz")

use retrocast_core::io::{read_json, write_json};

let evaluation: Evaluation = read_json(&path)?;
write_json(&output_path, &evaluation)?;

from retrocast.io import save_collected_candidates, save_evaluation

save_collected_candidates(predictions, "candidates.json.gz")
save_evaluation(evaluation, "evaluation.json.gz")

read_json and write_json infer gzip from the path. write_json_gz always uses RetroCast's deterministic, human-readable gzip representation. Native handles write schema-v2 artifacts without first materializing them in Python.

Runtime Identity

print(retrocast.__version__)
print(retrocast.__engine__)  # "rust"
print(retrocast.engine_info())

println!("{}", retrocast_core::VERSION);
println!("{}", retrocast_core::chem::version());

print(retrocast.__version__)

engine_info() reports the RetroCast version, RDKit C++, and the linked RDKit version.

Errors

• Python uses ValueError for invalid chemistry, malformed JSON data, or invalid producer schemas; OSError for missing or unreadable artifacts; and RuntimeError for adapter or workflow failures.
• Rust returns retrocast_core::error::EngineError from core operations.

See Error Handling for stable failure codes and candidate-level accounting.