molexp

An agent-assisted scientific-workflow platform for FAIR research

Documentation  ·  Quick start  ·  Ecosystem

molexp turns a Python script of typed tasks into a tracked, reproducible experiment. It pairs a content-hashed workflow engine with a file-system-backed Workspace → Project → Experiment → Run hierarchy, profile-driven run variants, and optional cluster submission — then layers on an audited orchestration harness (two-phase plan pipeline, artifact lineage, approval gates), an optional LLM agent that can plan and drive those workflows, and a FastAPI server with a bundled React UI.

Under active development. Public APIs may change between minor releases.

Vision

Research computation is rarely a single program — it is the same idea run many times, with different parameters, on different machines, until something works. The artifacts of that effort usually scatter: a script in one place, its outputs in another, the parameters in a notebook, the "which run was the good one" in someone's memory. molexp exists to close that gap, so the definition of an experiment and the record of every execution are one connected object instead of folklore.

It aspires to make reproducibility the default rather than a discipline. You write ordinary typed Python; molexp captures the workflow's content hash, the resolved configuration, the artifacts, the errors, and the execution history, and writes them down atomically as the run happens. The same workflow runs locally for a smoke test and on a cluster for the real thing, without changing the science — only where the worker process launches.

What that unlocks is a research workflow you can trust and revisit: experiments that re-run exactly, runs that can be compared and resumed, and a workspace that stays browsable — from the CLI or a web UI — long after the original author has moved on.

Capabilities

Module	Capability
molexp.workflow	Typed task-graph engine — WorkflowCompiler (decorator + OOP + protocol styles) compiles to a frozen, content-hashed CompiledWorkflow; WorkflowRuntime executes it with topology-driven parallelism, IR export, contract validation
molexp.workspace	File-system storage primitive — Workspace → Project → Experiment → Run Folder hierarchy, content-addressed assets, atomic JSON I/O, run lifecycle
molexp.config	In-code process-global config — a live molcfg.Config for runtime values such as LLM API keys, registered in code (never from env)
molexp.profile	File-based per-run config — molcfg.yaml loading and named profiles; resolves defaults + profiles into an immutable, content-hashed ProfileConfig
molexp.agent	Optional LLM layer — AgentRunner / AgentLoop (ChatLoop one round-trip, InteractiveLoop emergent tool loop) with persisted AgentSessions, built on PydanticAI (lazy-loaded)
molexp.harness	Experiment orchestrator — audited stages over a content-addressed Run (artifact lineage, approval gates, executors). Two modes: PlanOrchestrator (interactive planning behind a hard review gate, then deterministic realization into a compiled workflow) and ChatMode (exploratory, scratch-only). The production molexp plan entry point
molexp.services	Application-service layer between the shells and the domain layers — plan/curate runtimes, operator config, agent context, approval notifications. CLI and server both call it and never each other, so a Python operation and a UI operation share one code path
molexp.knowledge	Open Knowledge Format concept-type registry — the bottom-layer @concept_type registry workspace uses to reconstruct typed folders from each concept's persisted type
molexp.server	FastAPI app — REST routes for workspace, projects, experiments, runs, assets, execution, plus SSE streaming and bundled-SPA serving
molexp.cli	molexp command-line entry point — workspace init/info, run/execute, project / experiment / run / asset / target / session subcommands
molexp.plugins	On-demand capability registry — submit_molq scheduler bridge (SLURM / PBS / LSF) and gh GitHub client; core stays dependency-light
molexp.git	Thin async wrappers over the git binary — ensure_clone / fetch / push and GitWorktreeManager for per-experiment working dirs
ui/	React 19 + Rsbuild three-panel web client — navigation tree, entity viewers, inspector; compiled ahead of time and bundled into the wheel

Install

pip install molexp

Requires Python >= 3.14. Core depends on pydantic, typer, rich, fastapi, uvicorn, and the MolCrafts libraries mollog, molcfg, molq, and molpy (the workflow engine is self-owned — pydantic-graph is no longer a dependency). Optional extras: molexp[agent] adds the PydanticAI LLM layer; molexp[tensorboard] adds the TensorBoard scalar reader; molexp[all] bundles both, and molexp[dev] pulls everything for development.

Quick start

import asyncio

from molexp.workflow import WorkflowCompiler, WorkflowRuntime

wf = WorkflowCompiler(name="demo")


@wf.task
async def fetch() -> list[float]:
    return [1.0, 4.0, 9.0]


# A task receives an upstream's output by naming a parameter after that task —
# ``reduce`` binds ``fetch``'s output to its ``fetch`` argument (there is no
# ``ctx.inputs``: inputs are plain named parameters).
@wf.task(depends_on=["fetch"])
async def reduce(fetch: list[float]) -> float:
    return sum(fetch)


result = asyncio.run(WorkflowRuntime().execute(wf.compile()))
print(result.outputs)  # {'fetch': [1.0, 4.0, 9.0], 'reduce': 14.0}

Attaching a workflow to a tracked Workspace experiment (ws.project(...).experiment(...).run(wf.compile(), params=...)), running it with molcfg profiles via molexp run, and submitting to a cluster are covered in the docs.

Documentation

• Getting Started — runnable first workflow, tracked runs, CLI and profiles
• Concepts — the workflow / workspace / plugin mental model
• Guide — task & actor authoring, runtime, assets, server, molq
• Architecture — layer boundaries the code preserves
• Development — compiler internals, task protocols, active specs

MolCrafts ecosystem

Project	Role
molpy	Python toolkit — the shared molecular data model & workflow layer
molrs	Rust core — molecular data structures & compute kernels (native + WASM)
molpack	Packmol-grade molecular packing (Rust + Python)
molvis	WebGL molecular visualization & editing
molexp	Agent-assisted scientific-workflow platform for FAIR research — this repo
molnex	Molecular machine-learning framework
molq	Unified job queue — local / SLURM / PBS / LSF
molcfg	Layered configuration library
mollog	Structured logging, stdlib-compatible
molhub	Molecular dataset hub
molmcp	MCP server for the ecosystem
molrec	Atomistic record specification

Contributing

Contributions are welcome — see the development docs to get started.

License

BSD-3-Clause — see LICENSE.

---

_{Crafted with 💚 by MolCrafts}