Skip to main content

Researchium

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

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 init creates 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 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.

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

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

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

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