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, optional cluster submission, 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 — WorkflowBuilder (decorator + OOP + protocol styles), content-hashed Workflow, topology-driven parallelism, IR compiler, 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	molcfg.yaml loading and named profiles — resolves defaults + profiles into immutable, content-hashed per-run config
molexp.agent	Optional LLM harness — AgentRunner / AgentMode with chat / plan / review modes and persisted sessions, built on PydanticAI (lazy-loaded)
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.12. Core depends on pydantic, pydantic-graph, typer, rich, fastapi, uvicorn, and the MolCrafts libraries mollog, molcfg, and molq. Optional extras: molexp[agent] adds the PydanticAI LLM harness; molexp[all] and molexp[dev] pull everything for development.

Quick start

from molexp.workflow import TaskContext, WorkflowBuilder

builder = WorkflowBuilder(name="demo")


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


@builder.task(depends_on=["fetch"])
async def reduce(ctx: TaskContext) -> float:
    return sum(ctx.inputs)


workflow = builder.build()

Binding a workflow to a Workspace, running it with molcfg profiles, 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	Workflow & experiment-management platform — 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.

---