researchium 0.1.0__tar.gz

researchium-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run pytest
+      - run: uv run ruff check .

researchium-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+*.log

researchium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samarth Javagal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

researchium-0.1.0/PKG-INFO

@@ -0,0 +1,475 @@
+Metadata-Version: 2.5
+Name: researchium
+Version: 0.1.0
+Summary: A research module for organizing and analyzing scientific work.
+Project-URL: Homepage, https://github.com/samTheComputerArchitect/researchium
+Project-URL: Repository, https://github.com/samTheComputerArchitect/researchium
+Author: Samarth Javagal
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analysis,experiments,research,science
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build==1.6.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine==7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Researchium
+
+[![PyPI - Version](https://img.shields.io/pypi/v/researchium.svg)](https://pypi.org/project/researchium) [![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/researchium.svg)](https://pypi.org/project/researchium) [![PyPI - License](https://img.shields.io/pypi/l/researchium.svg)](LICENSE) [![Build Status](https://github.com/samTheComputerArchitect/researchium/actions/workflows/ci.yml/badge.svg)](https://github.com/samTheComputerArchitect/researchium/actions/workflows/ci.yml) [![PyPI - Downloads](https://img.shields.io/pypi/dm/researchium.svg)](https://pypi.org/project/researchium)
+
+**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](#quick-start)
+- [The environment layout](#the-environment-layout)
+- [Command-line usage](#command-line-usage)
+- [Writing run scripts](#writing-run-scripts)
+- [Python API](#python-api)
+- [File formats](#file-formats)
+- [Error handling](#error-handling)
+- [Development](#development)
+- [Project layout](#project-layout)
+
+---
+
+## Quick start
+
+```bash
+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:
+
+```python
+# 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:
+
+```bash
+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`
+
+```bash
+$ researchium init "Climate Genomics"
+Initialized researchium environment at /path/to/project
+```
+
+Creating an environment where one already exists fails with exit code `1`.
+
+### `create`
+
+```bash
+$ 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`.
+
+### `search`
+
+```bash
+$ 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`
+
+```bash
+$ 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](#writing-run-scripts).
+
+### `config` and `results`
+
+```bash
+$ 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:
+
+```python
+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
+
+```python
+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:
+
+```markdown
+### 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`):
+
+```json
+{
+  "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`:
+
+```markdown
+# 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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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
+
+```bash
+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.