Skip to main content

Researchium

PyPI - Version PyPI - Python Versions PyPI - License Build Status PyPI - Downloads

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:

  1. An environment owns a directory. researchium init lays down a standard structure (mirroring what git does with .git and uv with uv.lock). Every subsequent command discovers the environment by walking up from the current directory, so you can work from any subfolder.
  2. 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.
  3. Run scripts fill config and results. Write a normal Python script that imports Config and Results from researchium. researchium run executes it and snapshots both registries into Markdown and JSON files — ready for humans and machines.

Table of contents


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 from results/alpine-transcriptomics/, src/, or anywhere below the root.
  • Result folders are keyed by experiment name (results/<name>/), which keeps them readable while researchium 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.

$ 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}
  • Config and Results are plain mutable registries (dict-like). Use any key you like; order of the printed/.md output 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 a run.
  • The registries are cleared before every run, so runs never leak state.
  • run executes the script with runpy, as __main__. Anything the script print()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

  1. Add the function to the relevant module under src/researchium/.
  2. Export it from researchium/__init__.py and add it to __all__.
  3. Add tests under tests/; keep coverage at 100% (uv run pytest will show any missed lines).
  4. Run uv run ruff check . && uv run pytest and 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 starter run.py.
  • Experiment status (pending / running / completed) tracked in the registry.
  • Deleting and renaming experiments with safe migration of results.
  • A smaller researchium output 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)

Source distribution for researchium 0.1.0
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)

Table of built distributions (wheels) for researchium 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page