Generate molecules from a REINVENT4 prior model.

If dry_run=True: preview the TOML config without running. If dry_run=False: runs synchronously (sampling is fast) and returns results immediately.

For libinvent/linkinvent/mol2mol, smiles_file is required.

Generator guide:

• reinvent: de novo generation, no input SMILES needed

• libinvent: scaffold decoration, provide scaffold SMILES with [*:0] attachment points

• linkinvent: fragment linking, provide two warhead SMILES separated by |

• mol2mol: analogue generation, provide reference molecule SMILES

Fine-tune a REINVENT4 prior on a focused SMILES dataset (transfer learning).

If dry_run=True: preview the TOML config without writing or launching. If skip_validation=False (default): validates input SMILES and TOML before proceeding. Set launch=True to have the agent run the job (returns job_id for polling). Set launch=False (default) to get the config + command to run yourself.

After completion, the output model can be used as agent_file for RL.

Return the scoring-function design guide for an RL run, with AUTHORITATIVE score transform schemas introspected from the live REINVENT registry.

Use this as the source of truth for transforms: valid_transform_types lists every accepted transform (8 in REINVENT 4.7.x: sigmoid, reverse_sigmoid, double_sigmoid, step, left_step, right_step, value_mapping, exponential_decay) and transform_parameter_schemas gives each one's exact required/optional keys and defaults. Never use a transform type not in this list.

NOTE: This tool does NOT define scoring component names or their parameter schemas — those are injected separately (in the orchestrator via jobs/component_registry.json, which also carries the test_status / rl_compatible / sync_status readiness gate). Take component names and params from there; route missing components to /custom-component.

Steps: (1) identify objectives, (2) map objectives to components (from the component registry), (3) choose transforms (schemas here), (4) set weights, (5) confirm TOML.

Call this before reinvent_reinforcement_learning to collect the scoring config.

Run staged reinforcement learning (curriculum learning supported).

If dry_run=True: preview the TOML config without writing or launching. If skip_validation=False (default): validates input SMILES and TOML before proceeding.

Each stage in stages must contain:

• scoring: {components: [...], aggregation: "geometric_mean"}

• max_score: float

• min_steps: int

• max_steps: int

Each component in scoring.components:

• component_type: str (e.g. "QED", "MolecularWeight", "custom_alerts")

• name: str

• weight: float (default 1.0)

• transform: {type, ...params}

• params: dict (component-specific, e.g. smarts list)

• is_filter: bool (True for custom_alerts/MatchingSubstructure)

Call reinvent_rl_scoring_design_guide first to collect scoring config interactively.

Set launch=True to have the agent run the job. Set launch=False (default) to get the config + command to run yourself.

Validate SMILES/CSV input file before passing to REINVENT4.

Checks line counts, detects duplicates, validates each SMILES with RDKit, and applies generator-specific constraints (attachment points, fragments, etc.).

Args: smiles_file: Path to CSV or SMILES file generator: One of 'reinvent', 'libinvent', 'linkinvent', 'mol2mol' clean: If True, write _cleaned.smi with valid, deduplicated SMILES

Returns: { "valid": bool, "total_lines": int, "valid_smiles": int, "invalid_smiles": int, "duplicates": int, "cleaned_file": str (if clean=True), "errors": [{index, smiles, reason}, ...] (first 10) }

Validate a REINVENT4 TOML config before launch.

Attempts validation via 'reinvent --validate' (preferred) or via REINVENT4's Pydantic ReinventConfig model.

Args: toml_path_or_content: Path to config.toml or TOML content as string is_string: If True, treat input as TOML content

Returns: { "valid": bool, "errors": [{"field": str, "message": str}, ...], "warnings": [str, ...], "config_summary": dict (if valid) }

Generate a valid comp_*.py plugin file for REINVENT4.

Based on the canonical template from scoring_function.md. No reinstall needed — REINVENT4 discovers comp_*.py files at runtime.

IMPORTANT: Always provide implementation_code. Write the complete call body as plain unindented Python before calling this tool, then pass it here. Indentation is added automatically. This writes the full implementation in one atomic operation. If omitted, a TODO placeholder is written and the file cannot be edited afterward due to permissions.

When implementation_code is provided, the generated plugin is immediately smoke-tested (import, instantiate, call on sample SMILES, contract check). The test_result appears in the response; on failure, regenerate with corrected implementation_code.

Args: component_name: Python class name (e.g. 'MyQSARModel') description: What this component scores scoring_logic: How to compute the score — plain English, pseudocode, or code parameters: List of {name, type, description} dicts for user-configurable inputs component_tag: '_component' (standard), 'filter' (zeros total if 0), 'penalty' (multiplier) use_molcache: If True, call receives List[Chem.Mol]; else List[str] dependencies: External packages required output_dir: Where to write comp*.py (default: reinvent_plugins/components/) implementation_code: Complete body of call as unindented Python. test_after_generate: Run the smoke test after writing (default True). test_smiles: Override SMILES used by the smoke test. test_params: Per-endpoint parameter values for the smoke test, e.g. {"threshold": 0.5} — scalars are list-wrapped automatically.

Returns file path, source code, TOML snippet, and test_result (when tested).

Smoke-test a comp_*.py plugin on sample SMILES without running RL.

Loads the plugin (catching import errors), instantiates the tagged component, calls it on a mix of valid + invalid SMILES, and asserts the REINVENT4 plugin contract (returns ComponentResults with np.ndarray of floats, correct length, NaN for invalid inputs).

Use this after manually editing a comp_*.py, or to re-verify with custom SMILES / parameters. For freshly generated files, the smoke test is already auto-run by reinvent_custom_scoring_component.

Args: file_path: Absolute path to the comp_*.py file (must live under .../reinvent_plugins/components/ so relative imports resolve). test_smiles: SMILES to score. Defaults to a built-in mix of valid + invalid + edge cases. params: Per-endpoint parameter values, e.g. {"threshold": 0.5}. class_name: Component class name. Auto-detected when omitted.

Returns: dict with status (pass/fail), errors, warnings, per-SMILES scores, timing_ms_per_mol, and ready_for_rl flag.

Register a user-launched REINVENT4 job for status tracking.

Use after running the suggested_cmd yourself. The agent can then poll progress with reinvent_job_status. Optionally attach the process PID with reinvent_attach_pid for live polling.

Args: run_type: 'transfer_learning' or 'staged_learning' workdir: Path to the run's working directory job_id: Optional custom ID (auto-generated if omitted) log_file: Path to log file (default: /reinvent.log) config_path: Path to TOML config (default: /config.toml)

Attach a process ID to a registered user job for live polling.

After running a job manually and registering it with reinvent_register_job, call this to attach the PID. The server can then use os.kill(pid, 0) to check if the process is still running, improving polling reliability.

Args: job_id: Job ID from reinvent_register_job pid: Process ID of the running reinvent job

Poll the status of any registered REINVENT4 TL or RL job.

Works for both agent-launched and user-registered jobs. Returns: running/completed/failed status, log tail, current epoch, and (on completion) result summaries, top SMILES, checkpoint paths.

Args: job_id: ID from reinvent_transfer_learning, reinvent_reinforcement_learning, or reinvent_register_job

Inspect columns or generate optimisation history plots for a REINVENT4 RL run.

Works mid-run and post-run — plots whatever step data exists at call time. Provide job_id (looks up workdir from registry) OR csv_path directly. job_id takes precedence if both are given.

TWO-CALL PROTOCOL: Call 1 — extra_columns=None (inspect mode): Returns column categorisation (standard, plottable, metadata). No plots are generated. Agent presents plottable_columns to user.

Call 2 — extra_columns=[...] (plot mode): Generates PNGs for Agent, Prior, Target, Score (always) + extra_columns. Saves to output_dir (default: /plots/). Returns paths of all saved PNG files.

Args: job_id: Job ID from reinvent_register_job or reinvent_reinforcement_learning csv_path: Direct path to a stage CSV file (for ad-hoc / finished run analysis) extra_columns: None for inspect; list of column names to plot beyond the standard 4 output_dir: Where to save PNGs (default: /plots/ or /plots/)

Evaluate a set of generated SMILES across multiple quality dimensions.

Designed for raw sampling output (CSV or .smi) from reinvent_sampling, but works with any SMILES file. Writes an analysis_report.json and per_molecule.csv to disk and returns a structured summary to the agent.

Evaluators available: Always: validity, physicochemical, druglikeness, scaffold, alerts, diversity With ref: similarity, novelty, coverage (auto-skipped if no ref_smiles_file)

physicochemical covers: MW, LogP, TPSA, HBD, HBA, rotatable bonds, num atoms (incl. H), num heavy atoms, num heteroatoms, fraction heteroatoms, num rings, num aromatic rings, num aliphatic rings. druglikeness covers: QED, Lipinski RO5, Veber rules, SA score (if available). scaffold: Bemis-Murcko scaffold count and diversity. alerts: PAINS and Brenk structural alert rates. diversity: internal diversity (1 − mean pairwise Tanimoto, ECFP4). similarity: nearest-neighbour Tanimoto to reference set. novelty: % generated SMILES not present in reference (exact canonical match). coverage: % reference molecules with ≥1 generated neighbour at Tanimoto ≥ 0.4.

When plots=True, generates PNGs: physicochemical_dist.png — MW/LogP/TPSA/HBD/HBA/QED(/SA) histograms atom_profile.png — num atoms/heavy/hetero/frac_het/rotbonds/rings atom_types.png — element frequency bar chart (C/N/O/S/halogens/…) ring_profile.png — total/aromatic/aliphatic ring histograms similarity_hist.png — NN Tanimoto to ref (if ref provided) umap_projection.png — ECFP4 UMAP; requires umap-learn

Args: smiles_file: Path to sampling CSV or .smi file (SMILES col auto-detected). ref_smiles_file: Optional reference / known-active SMILES file. evaluators: List of evaluator names, or "all" (default). plots: Generate PNG plots (default True). Set False to skip all visualisation. color_by: Property to colour generated UMAP points (viridis). Any column in per_molecule.csv: "qed", "mw", "sa_score", "logp", "tpsa", etc. Default None = generated blue / reference red. output_dir: Where to write outputs (default: _analysis/ next to input).