Skip to main content

Researchium

PyPI - Version PyPI - Python Versions PyPI - License PyPI - Downloads

Version 0.3.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 init creates a new folder and sets up the standard structure inside it (experiments/, results/, a Markdown log) and marks it as a Researchium project. cd into 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 run runs 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/Results are captured and written to disk exactly as for in-process runs;
  • the researchium package 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).

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 starter run.py.
  • Experiment status (pending / running / completed).
  • Deleting and renaming experiments.
  • A --json output flag for scripting.

Metadata

Release files for researchium 0.3.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.3.0
File Size Uploaded Provenance Actions
researchium-0.3.0.tar.gz 22.3 kB Without provenance Details for researchium-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for researchium 0.3.0
File Interpreter ABI Platform Actions
researchium-0.3.0-py3-none-any.whl Python 3 none any Details for researchium-0.3.0-py3-none-any.whl

Total release size: 42.2 kB

Release files / researchium-0.3.0.tar.gz

Download URL researchium-0.3.0.tar.gz
Size 22.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4fcf07343ec1144f6adbe567da34a13c8b357c3155dc786b71b543af4f3b4a9e
BLAKE2b-256 checksum
How to use checksums
fba7b8844748dce519aaf727b116fd313ca55487bbe0e11e1b5580eb5d8f4a66
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.3.0-py3-none-any.whl

Download URL researchium-0.3.0-py3-none-any.whl
Size 19.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b4658e5b41672f8f0e7872c2d107eb60617248138e010291816efb45ee02b386
BLAKE2b-256 checksum
How to use checksums
30fbdaf1de8fca0c0d4ddffd8986986d6c0d7d73f995b7b9cb2f6ad73995501b
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.3.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