Researchium
Version 0.1.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"
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 standard folder structure (experiments/,results/, a Markdown log) and marks the directory as a Researchium project.- Commands find the project by walking up from wherever you are, so you can run them from any subfolder.
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.
Commands
Every command accepts an experiment by name or by its short ID.
| Command | What it does |
|---|---|
researchium init NAME |
Set up a research project in the current directory. |
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. |
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/
├── 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. |
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.2.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.2.0.tar.gz | 18.9 kB | Without provenance | Details for researchium-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| researchium-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for researchium-0.2.0-py3-none-any.whl |
Total release size: 36.0 kB
Release files / researchium-0.2.0.tar.gz
| Download URL | researchium-0.2.0.tar.gz |
|---|---|
| Size | 18.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
82a163e616fbca191d12e309a57e1c571c5567686839d253c693d40f0973a230
|
|
BLAKE2b-256 checksum How to use checksums |
27f0124057417518a0e45c19eca426e6c1a4b655f83d639ab5e8656f8c3bc4ea
|
| 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.2.0-py3-none-any.whl
| Download URL | researchium-0.2.0-py3-none-any.whl |
|---|---|
| Size | 17.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8df91d2101375c38440402e73bac7f2fe178c135b3f7ed14de8ea748ed7e3d79
|
|
BLAKE2b-256 checksum How to use checksums |
65a3e9cf16dcb64d5187102e9dd27b224ed250e649ac6d1a5246ea417a8f632c
|
| 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.2.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.