---

name: experiment-core description: "Build, run, and compose Sacred experiments with Experiment, Ingredient, Run, captured functions, commands, resources, artifacts, and programmatic execution." disable-model-invocation: true metadata: disco-role: operating license: MIT

experiment-core

Use this sub-skill when you need to design or modify the Python core of a Sacred 0.8.7 experiment: Experiment, Ingredient, Run, captured functions, commands, hooks, resources, artifacts, scalar metrics, and programmatic execution.

Read this first

• Read references/experiment-workflows.md when implementing a new experiment module, converting plain Python into Sacred structure, composing reusable ingredients, or choosing between @ex.main, @ex.automain, ex.run, and ex.run_commandline.
• Read references/api-reference.md when you need constructor or method signatures, return-value expectations, special captured arguments, or lifecycle details for Run objects.
• Read references/troubleshooting.md when a run fails around automain placement, interactive/Jupyter safeguards, missing config values, unexpected config injection, read-only config mutation, file tracking, or the “No observers” warning.
• Run scripts/sacred_experiment_smoke.py after changing Sacred-related runtime assumptions or validating an installed environment. It uses only temporary files and an in-process interactive=True experiment.

Route elsewhere

• For detailed command-line update syntax, named-config syntax, and CLI flag catalogs, use the configuration-and-cli sub-skill.
• For FileStorageObserver, MongoObserver, storage layout, and observer-specific logging persistence, use the observers-and-logging sub-skill.
• For seeding, _seed/_rnd, capture modes, stdout filtering, and reproducibility policy, use the reproducibility-and-capture sub-skill.

Operating rules

• Treat every @ex.main, @ex.automain, @ex.command, @ing.command, @ex.capture, and @ing.capture function as a captured function whose missing parameters may be filled from configuration by name.
• Prefer @ex.main plus explicit ex.run(...) for tests, notebooks, libraries, and multi-run orchestration. Use @ex.automain only in executable scripts and place the decorated function at the end of the file.
• Use Experiment(..., interactive=True) with an explicit name for notebook/REPL-style code; otherwise Sacred protects reproducibility by rejecting interactive definitions.
• Use ingredients for reusable configurable components. Their config appears under the ingredient path, and ingredient commands are run by dotted command names.
• Access run-time objects through special captured arguments (_run, _config, _log) rather than globals when possible. Do not mutate _config or nested config containers.
• Call open_resource, add_resource, add_artifact, and log_scalar only during an active run, either from the Experiment object or the captured _run object.