Researchium
Version 0.1.0
Researchium is a small, opinionated toolkit for organizing scientific work into self-contained environments and tracking experiments within them. It gives every experiment a stable ID, a home folder, a runnable script, and a place for its configuration and results — all stored as plain, human-readable files so nothing is locked in a database.
It is built around three ideas:
- An environment owns a directory.
researchium initlays down a standard structure (mirroring whatgitdoes with.gitanduvwithuv.lock). Every subsequent command discovers the environment by walking up from the current directory, so you can work from any subfolder. - Experiments are first-class. Each experiment is a folder in
experiments/, has a unique short ID, and keeps its configuration and results in its own location. - Run scripts fill config and results. Write a normal Python script that
imports
ConfigandResultsfromresearchium.researchium runexecutes it and snapshots both registries into Markdown and JSON files — ready for humans and machines.
Table of contents
- Quick start
- The environment layout
- Command-line usage
- Writing run scripts
- Python API
- File formats
- Error handling
- Development
- Project layout
Quick start
researchium init "Climate Genomics" # lay down an environment
researchium create alpine-transcriptomics \
"RNA-seq of alpine vs lowland populations." # register an experiment
Write a run script:
# experiments/alpine-transcriptomics/run.py
from researchium import Config, Results
Config["epochs"] = 10
Config["learning_rate"] = 0.001
Results["mse"] = 0.032
Results["r2"] = 0.91
Run it and inspect:
researchium run alpine-transcriptomics # or by ID: researchium run 1e70f7c3
researchium config alpine-transcriptomics # epochs: 10
researchium results alpine-transcriptomics # mse: 0.032
researchium search alpine # find experiments and their IDs
The environment layout
researchium init NAME creates a directory with this structure:
my-study/
├── .researchium/ # marker + environment metadata (like .git/)
│ └── environment.json
├── experiments/ # one folder per experiment
├── results/ # one folder per experiment, mirroring experiments/
├── src/ # reusable code for the project
├── experiments.md # human log of every experiment
└── experiments.json # machine-readable registry of experiments
After registering and running an experiment, an experiment looks like:
experiments/
└── alpine-transcriptomics/
├── run.py # you write this
├── config.md # written by `run`
└── config.json
results/
└── alpine-transcriptomics/
├── results.md
└── results.json
Key details:
- The
.researchium/marker is what makes a directory an environment.discover_environment()walks up parent directories to find it, so commands work fromresults/alpine-transcriptomics/,src/, or anywhere below the root. - Result folders are keyed by experiment name (
results/<name>/), which keeps them readable whileresearchium results <name_or_id>still resolves either form. - Results and config are stored as both Markdown (for humans) and JSON (for tooling).
Command-line usage
Every command accepts an experiment either by exact name or by ID.
| Command | Description |
|---|---|
researchium init NAME |
Create an environment named NAME in the current directory. |
researchium create NAME DESC |
Register an experiment: folder + log entry + registry record. |
researchium search QUERY |
Find experiments matching name or description (case-insensitive). |
researchium run NAME_OR_ID |
Execute experiments/<name>/run.py, snapshot config + results. |
researchium config NAME_OR_ID |
Print the experiment config as key: value lines. |
researchium results NAME_OR_ID |
Print the experiment results as key: value lines. |
init
$ researchium init "Climate Genomics"
Initialized researchium environment at /path/to/project
Creating an environment where one already exists fails with exit code 1.
create
$ researchium create alpine-transcriptomics "RNA-seq of alpine vs lowland populations."
Created experiment alpine-transcriptomics (ID 1e70f7c3) at .../experiments/alpine-transcriptomics
create refuses empty or path-traversal names (e.g. ../x) and duplicate
names. It also creates the experiment's results/<name>/ folder and appends a
date/description/ID entry to experiments.md.
search
$ researchium search alpine
- alpine-transcriptomics (ID 1e70f7c3): RNA-seq of alpine vs lowland populations.
Matching is case-insensitive over both name and description. No matches prints
No experiments matching 'query'. and still exits 0.
run
$ researchium run alpine-transcriptomics
Ran experiment alpine-transcriptomics (ID 1e70f7c3)
config -> experiments/alpine-transcriptomics/config.md, config.json
results -> results/alpine-transcriptomics/results.md, results.json
run clears the previous Config/Results, executes
experiments/<name>/run.py, then writes four files. It fails with exit code
1 if the script is missing or the script raises. See
Writing run scripts.
config and results
$ researchium config alpine
epochs: 10
learning_rate: 0.001
$ researchium results alpine
mse: 0.032
r2: 0.91
Structured values (lists, dicts) print as compact JSON, e.g.
metrics: {"loss": 0.2}. Before the first run, config prints
(no configuration yet); results falls back to a file listing of the
results folder.
Writing run scripts
A run script is any Python file named run.py inside an experiment folder. It
should import Config/Results and set values by key:
from researchium import Config, Results
import numpy as np
from sklearn.model_selection import train_test_split
Config["epochs"] = 10
Config["optimizer"] = "adam"
Config["layers"] = [256, 128, 64]
# ... your training code ...
accuracy = 0.93
Results["accuracy"] = accuracy
Results["metrics"] = {"precision": 0.91, "recall": 0.89}
ConfigandResultsare plain mutable registries (dict-like). Use any key you like; order of the printed/.mdoutput follows insertion order.- Values that are lists, tuples, or dicts are stored as JSON; any other object
is stored via
str()— so non-JSON values (e.g. numpy types) never crash arun. - The registries are cleared before every run, so runs never leak state.
runexecutes the script withrunpy, as__main__. Anything the scriptprint()s appears on the CLI output.
Python API
Everything below is importable from the top-level researchium package.
Environments
| Function | Description |
|---|---|
initialize_environment(path, name=None) |
Create the standard structure + .researchium/ marker. Returns Environment. |
is_initialized(path) |
True if path is directly an environment root. |
discover_environment(path) |
Nearest environment at/above path. Raises EnvironmentNotFoundError. |
Environment (dataclass) |
root, name, created, researchium_version; properties experiments_dir, src_dir, results_dir, experiments_notebook, experiments_registry. |
load_experiments_registry(path) |
Read experiment records from experiments.json. |
save_experiments_registry(path, records) |
Write experiment records to experiments.json. |
Experiments
| Function | Description |
|---|---|
create_experiment(name, description, path) |
Register an experiment and return it. Raises ExperimentExistsError. |
list_experiments(path) |
All experiments, sorted by name. |
search_experiments(query, path) |
Experiments matching name/description. |
get_experiment(identifier, path) |
Look up by ID or name. Raises ExperimentNotFoundError. |
get_experiment_results(identifier, path) |
Result files (paths) of an experiment. |
Experiment (dataclass) |
id, name, description, created, environment; properties path, results_dir. |
Runtime
| Function | Description |
|---|---|
Config, Results |
Mutable registries your run script fills in. |
run_experiment(identifier, path) |
Execute the run script and persist outputs. Raises RunScriptNotFoundError / RunFailedError. |
format_configuration(identifier) |
Config as key: value lines. |
format_run_results(identifier) |
Results as key: value lines (listing fallback). |
Example
from researchium import (
Config,
Results,
create_experiment,
discover_environment,
initialize_environment,
run_experiment,
)
env = initialize_environment("~/study", name="Climate Genomics")
experiment = create_experiment(
"climate-model", "Temperature projections for 2050.", "~/study"
)
experiment.path.joinpath("run.py").write_text(
"from researchium import Config, Results\n"
"Config['seed'] = 42\n"
"Results['mae'] = 1.7\n"
)
run_experiment(experiment.name, "~/study") # runs + writes files
with open(experiment.path / "config.json") as fh:
print(fh.read())
# From anywhere inside the project:
env = discover_environment(".") # finds it by walking up
File formats
experiments.md
A human log. create appends a section per experiment:
### alpine-transcriptomics
RNA-seq of alpine vs lowland populations.
- ID: `1e70f7c3`
- Created: 2026-09-22
- Folder: `experiments/alpine-transcriptomics`
experiments.json
The machine-readable registry (created empty by init, appended by create):
{
"version": 1,
"experiments": [
{
"id": "1e70f7c3",
"name": "alpine-transcriptomics",
"description": "RNA-seq of alpine vs lowland populations.",
"created": "2026-09-22"
}
]
}
config.md / results.md
Human-formatted snapshots written by run:
# alpine-transcriptomics
Last run: 2026-09-22 23:08
## Configuration
- **epochs**: 10
- **learning_rate**: 0.001
config.json / results.json
The same data as JSON, suitable for programmatic consumption:
{
"epochs": 10,
"learning_rate": 0.001
}
Note: a stale readme.md produced by a development build is removed
automatically on the next run.
.researchium/environment.json
Environment metadata; this directory is the environment marker:
{
"name": "Climate Genomics",
"created": "2026-09-22",
"researchium": "0.1.0"
}
Error handling
All domain errors subclass researchium.ResearchiumError:
| Error | Raised when |
|---|---|
EnvironmentExistsError |
init on an already-initialized directory |
EnvironmentNotFoundError |
no environment at/above the given path |
ExperimentExistsError |
creating a duplicate experiment name |
ExperimentNotFoundError |
no experiment matches the ID/name |
InvalidExperimentNameError |
empty or path-traversal experiment name |
RunScriptNotFoundError |
experiment has no run.py |
RunFailedError |
the run script raised |
The CLI catches these, prints error: <message> to stderr, and exits 1.
Development
uv sync --extra dev # install the package + dev tools
uv run pytest # 44 tests
uv run pytest -q # keep it quiet
uv run ruff check . # lint (E, F, W, I, UP on src + tests)
Test coverage is configured in pyproject.toml (--cov=researchium --cov-report=term-missing) and is kept at 100%. The GitHub Actions workflow in
.github/workflows/ci.yml runs tests and lint on Python 3.10 / 3.12 / 3.14.
Adding a feature
- Add the function to the relevant module under
src/researchium/. - Export it from
researchium/__init__.pyand add it to__all__. - Add tests under
tests/; keep coverage at 100% (uv run pytestwill show any missed lines). - Run
uv run ruff check . && uv run pytestand reinstall the global tool if you use it:uv tool install --force /path/to/researchium.
Project layout
researchium/
├── pyproject.toml # PEP 621 metadata, hatchling build, ruff/pytest config
├── uv.lock # locked development dependencies
├── README.md
├── .python-version
├── .github/workflows/ci.yml # lint + tests matrix
├── src/researchium/
│ ├── __init__.py # public API surface
│ ├── environment.py # init, discovery, environment metadata + registry
│ ├── experiments.py # experiment lifecycle, search, lookup
│ ├── runtime.py # Config/Results registries + runner + formatters
│ └── cli.py # argparse-based CLI (entry point `researchium`)
└── tests/
├── test_environment.py
├── test_experiments.py
├── test_runtime.py
└── test_cli.py
Roadmap
Planned directions, in rough order:
researchium scaffold <name>to generate a starterrun.py.- Experiment status (pending / running / completed) tracked in the registry.
- Deleting and renaming experiments with safe migration of results.
- A smaller
researchiumoutput format flag (--json) for scripting.
Metadata
Release files for researchium 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| researchium-0.1.0.tar.gz | 15.7 kB | Without provenance | Details for researchium-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| researchium-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for researchium-0.1.0-py3-none-any.whl |
Total release size: 30.9 kB
Release files / researchium-0.1.0.tar.gz
| Download URL | researchium-0.1.0.tar.gz |
|---|---|
| Size | 15.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
641980c878d884fef45fc0a85d0c6e1ab0817a87007fb3992f1f7fead720f33f
|
|
BLAKE2b-256 checksum How to use checksums |
1e6a46a769997924ff852683736d17dbd29b4261bd04fac23d761441ce528455
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / researchium-0.1.0-py3-none-any.whl
| Download URL | researchium-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
73b3fab823bc15d8cbe286b36abfde0f9dfb8d27ca7414a34666f725eb3fc9fd
|
|
BLAKE2b-256 checksum How to use checksums |
d5eb3c38d78d4a7e3b1d5631b9c4056eb8cf5046f6b54c5072c0fd7762803c35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for researchium 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.