Researchium
Version 0.4.0
Researchium is a tiny toolkit for keeping your scientific experiments organized on disk — no database, no server, no web app. Each experiment gets a stable ID, a folder for your code, and a readable record of its configuration and results.
Install
pip install researchium
Quick start
Set up a project and register an experiment:
researchium init climate-genomics # creates a climate-genomics/ folder
cd climate-genomics
researchium create alpine-transcriptomics "RNA-seq of alpine vs lowland populations."
Write a run script:
# experiments/alpine-transcriptomics/run.py
from researchium import Config, Results
Config["epochs"] = 10
Config["learning_rate"] = 0.001
# ... your training code ...
Results["mse"] = 0.032
Results["r2"] = 0.91
Run it and inspect the results:
researchium run alpine-transcriptomics # runs run.py, saves config + results
researchium config alpine-transcriptomics # epochs: 10
researchium results alpine-transcriptomics # mse: 0.032
researchium search alpine # find experiments and their IDs
How it works
researchium initcreates a new folder and sets up the standard structure inside it (experiments/,results/, a Markdown log) and marks it as a Researchium project.cdinto it to start working.- Commands find the project by walking up from wherever you are, so you can run them from any subfolder of the project.
researchium runruns your script and snapshots the configuration and results it records — as Markdown for humans and JSON for tooling. Everything is plain text; nothing is locked in a database.
Using a virtual environment
By default researchium run executes the experiment script in the same Python
that drives the CLI. To instead run experiments inside a dedicated virtual
environment, point researchium venv at one:
researchium venv .venv # a venv directory inside the project
researchium venv /opt/envs/sandbox # or any python executable path
researchium venv # show the current setting
researchium venv --unset # go back to in-process runs
The path is stored in the project's .researchium/environment.json (relative
paths resolve against the project root, so .venv works from any subfolder).
When a venv is set, run launches the experiment's script under that
environment's interpreter as a subprocess:
- the script's
print()output still streams to your terminal; Config/Resultsare captured and written to disk exactly as for in-process runs;- the
researchiumpackage the script imports is the one driving the CLI, so no install inside the venv is required.
Commands
Every command accepts an experiment by name or by its short ID.
| Command | What it does |
|---|---|
researchium init NAME |
Create a NAME/ folder and set it up as a project. |
researchium create NAME DESC |
Register an experiment with a description. |
researchium search QUERY |
Find experiments by name or description. |
researchium run NAME_OR_ID |
Run the experiment's script and record config + results. |
researchium config NAME_OR_ID |
Show an experiment's configuration. |
researchium results NAME_OR_ID |
Show an experiment's results. |
researchium compare ID... --main ID |
Short AI verdict on how the main experiment fares. |
researchium venv [PATH] |
Set the Python that run uses (--unset to clear). |
researchium agent |
Print an agent-facing guide to using researchium. |
Writing run scripts
A run script is any Python file named run.py in the experiment's folder. It
imports two dict-like registries from researchium and fills them in:
from researchium import Config, Results
Config["epochs"] = 10
Config["layers"] = [256, 128, 64] # lists/dicts are stored as JSON
Results["accuracy"] = 0.93
Results["metrics"] = {"precision": 0.91} # any other value is stored as text
- The registries are cleared before every run, so runs never leak state.
- Anything your script
print()s shows up on the command line.
Calling an OpenAI-compatible API
Work with OpenAI or any compatible endpoint (local servers included) from a run script:
from researchium import AIClient
client = AIClient() # reads OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL
explanation = client.complete("Summarize these results in one sentence.")
Results["summary"] = explanation
AIClient(api_key=..., base_url=..., model=...) posts to
{base_url}/chat/completions. Constructor arguments win over environment
variables.
Comparing experiments
From the command line:
researchium compare membrane-b catalyst --main membrane-a
Prints a short plain-text verdict on how the main experiment fares against the others — up to four sentences, straight from your AI endpoint to the terminal.
The same comparison is available from Python:
from researchium import compare_results
# Markdown report written from the main experiment's point of view
report = compare_results("climate-model", main="alpine-transcriptomics")
# Short plain-text verdict, ready for a terminal
verdict = compare_results("climate-model", main="alpine-transcriptomics", terminal=True)
compare_results(*others, main=...) sends the main experiment's readme.md,
config.md and results.md — plus the same files for the other experiments,
clearly labeled — to your AI endpoint. The comparison is always written from
the main experiment's point of view.
terminal=False(default): structured Markdown report with fixed sections (Verdict, Configuration differences, Results comparison, Strengths and weaknesses, Anomalies and caveats, Recommendation).terminal=True: a short plain-text verdict of a few sentences.
Requires a configured AIClient; pass prompt=... to replace the default
instructions.
What gets stored
After init and a run, your project looks like this:
my-study/
├── .researchium/
│ └── environment.json # project metadata + optional `python` (venv) setting
├── experiments/
│ └── alpine-transcriptomics/
│ ├── run.py # your script
│ ├── readme.md # notes about the experiment (created by create)
│ ├── config.md # config snapshot (human-readable)
│ └── config.json # same data, for tooling
├── results/
│ └── alpine-transcriptomics/
│ ├── results.md
│ └── results.json
└── experiments.md # a log of every experiment
Python API
The same features are available from Python code:
| Function | What it does |
|---|---|
initialize_environment(path, name) |
Create a project at path. |
discover_environment(path) |
Find the nearest project from path. |
set_python(path, python) |
Configure the interpreter run uses. |
create_experiment(name, description) |
Register an experiment. |
get_experiment(identifier) |
Look up an experiment by ID or name. |
run_experiment(identifier) |
Run a script and save its output. |
AIClient(api_key=...) |
Talk to any OpenAI-compatible endpoint. |
compare_results(*others, main=...) |
Main experiment vs others; terminal=True for plain-text verdict. |
All errors subclass researchium.ResearchiumError.
Roadmap
researchium scaffold <name>to generate a starterrun.py.- Experiment status (pending / running / completed).
- Deleting and renaming experiments.
- A
--jsonoutput flag for scripting.
Metadata
Release files for researchium 0.4.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.4.0.tar.gz | 23.9 kB | Without provenance | Details for researchium-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| researchium-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for researchium-0.4.0-py3-none-any.whl |
Total release size: 45.7 kB
Release files / researchium-0.4.0.tar.gz
| Download URL | researchium-0.4.0.tar.gz |
|---|---|
| Size | 23.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
74f562ab72603fe6c794853f4dafb618d946d3acfd67780fc63b9199a5d4aa13
|
|
BLAKE2b-256 checksum How to use checksums |
d3dd3a235ad399644c9420cba2dd5ff14e4a2ca28a2930c2aa58594f3472b6d6
|
| 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.4.0-py3-none-any.whl
| Download URL | researchium-0.4.0-py3-none-any.whl |
|---|---|
| Size | 21.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1ffbb4c6ac5e7ce65149305548bd3ec1ba73460045bbd75e1e91bfeb42abf98e
|
|
BLAKE2b-256 checksum How to use checksums |
f6c076bd69339f5b4f9c008954ae7aaf1d697f798ec9c69755b580e48238b635
|
| 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.4.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.