researchium 0.1.0__py3-none-any.whl

researchium/__init__.py

@@ -0,0 +1,59 @@
+"""Researchium - a research module for organizing and analyzing scientific work."""
+
+from researchium.environment import (
+    Environment,
+    EnvironmentExistsError,
+    EnvironmentNotFoundError,
+    ResearchiumError,
+    discover_environment,
+    initialize_environment,
+    is_initialized,
+)
+from researchium.experiments import (
+    Experiment,
+    ExperimentExistsError,
+    ExperimentNotFoundError,
+    InvalidExperimentNameError,
+    create_experiment,
+    get_experiment,
+    get_experiment_results,
+    list_experiments,
+    search_experiments,
+)
+from researchium.runtime import (
+    Config,
+    Results,
+    RunFailedError,
+    RunScriptNotFoundError,
+    format_configuration,
+    format_run_results,
+    run_experiment,
+)
+
+__all__ = [
+    "Config",
+    "Environment",
+    "EnvironmentExistsError",
+    "EnvironmentNotFoundError",
+    "Experiment",
+    "ExperimentExistsError",
+    "ExperimentNotFoundError",
+    "InvalidExperimentNameError",
+    "ResearchiumError",
+    "Results",
+    "RunFailedError",
+    "RunScriptNotFoundError",
+    "create_experiment",
+    "discover_environment",
+    "format_configuration",
+    "format_run_results",
+    "get_experiment",
+    "get_experiment_results",
+    "initialize_environment",
+    "is_initialized",
+    "list_experiments",
+    "run_experiment",
+    "search_experiments",
+]
+
+__version__ = "0.1.0"

researchium/cli.py

@@ -0,0 +1,109 @@
+"""Command-line interface for Researchium."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from researchium import (
+    ResearchiumError,
+    create_experiment,
+    format_configuration,
+    format_run_results,
+    initialize_environment,
+    run_experiment,
+    search_experiments,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="researchium", description="Organize and track research experiments."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init = subparsers.add_parser("init", help="Initialize a research environment.")
+    init.add_argument("name", help="Name of the research project.")
+
+    create = subparsers.add_parser("create", help="Create a new experiment.")
+    create.add_argument("name", help="Experiment name (used as the folder name).")
+    create.add_argument("description", help="Brief description of the experiment.")
+
+    search = subparsers.add_parser(
+        "search", help="Search experiments by name or description."
+    )
+    search.add_argument("query", help="Text to search for.")
+
+    config = subparsers.add_parser(
+        "config", help="Show an experiment's configuration as key: value lines."
+    )
+    config.add_argument("identifier", help="ID or name of the experiment.")
+
+    results = subparsers.add_parser(
+        "results", help="Show an experiment's results as key: value lines."
+    )
+    results.add_argument("identifier", help="ID or name of the experiment.")
+
+    run = subparsers.add_parser(
+        "run", help="Run an experiment's script and store its config and results."
+    )
+    run.add_argument("identifier", help="ID or name of the experiment.")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return _dispatch(args)
+    except ResearchiumError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    if args.command == "init":
+        env = initialize_environment(name=args.name)
+        print(f"Initialized researchium environment at {env.root}")
+        return 0
+
+    if args.command == "create":
+        experiment = create_experiment(args.name, args.description)
+        print(
+            f"Created experiment {experiment.name} "
+            f"(ID {experiment.id}) at {experiment.path}"
+        )
+        return 0
+
+    if args.command == "search":
+        experiments = search_experiments(args.query)
+        if not experiments:
+            print(f"No experiments matching {args.query!r}.")
+            return 0
+        for experiment in experiments:
+            print(
+                f"- {experiment.name} (ID {experiment.id}): {experiment.description}"
+            )
+        return 0
+
+    if args.command == "config":
+        print(format_configuration(args.identifier))
+        return 0
+
+    if args.command == "results":
+        print(format_run_results(args.identifier))
+        return 0
+
+    if args.command == "run":
+        experiment = run_experiment(args.identifier)
+        print(f"Ran experiment {experiment.name} (ID {experiment.id})")
+        print(f"  config  -> experiments/{experiment.name}/config.md, config.json")
+        print(f"  results -> results/{experiment.name}/results.md, results.json")
+        return 0
+
+    raise SystemExit("unknown command")  # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

researchium/environment.py

@@ -0,0 +1,179 @@
+"""Environment awareness: initialize and discover Researchium environments.
+
+An environment is a directory carrying a hidden ``.researchium/`` marker,
+mirroring how ``git`` owns a directory with ``.git`` and ``uv`` owns one with
+``uv.lock``. Any command that needs context reports the nearest environment
+found by walking up from the current directory.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+import researchium
+
+MARKER_DIR_NAME = ".researchium"
+METADATA_FILE_NAME = "environment.json"
+EXPERIMENTS_NOTEBOOK = "experiments.md"
+EXPERIMENTS_REGISTRY = "experiments.json"
+REGISTRY_VERSION = 1
+
+
+class ResearchiumError(Exception):
+    """Base error raised by Researchium."""
+
+
+class EnvironmentExistsError(ResearchiumError):
+    """Raised when initializing an already-initialized directory."""
+
+
+class EnvironmentNotFoundError(ResearchiumError):
+    """Raised when no environment can be discovered from a directory."""
+
+
+@dataclass(frozen=True)
+class Environment:
+    """A discovered Researchium environment."""
+
+    root: Path
+    name: str
+    created: date
+    researchium_version: str
+
+    @property
+    def experiments_dir(self) -> Path:
+        return self.root / "experiments"
+
+    @property
+    def src_dir(self) -> Path:
+        return self.root / "src"
+
+    @property
+    def results_dir(self) -> Path:
+        return self.root / "results"
+
+    @property
+    def experiments_notebook(self) -> Path:
+        return self.root / EXPERIMENTS_NOTEBOOK
+
+    @property
+    def experiments_registry(self) -> Path:
+        return self.root / EXPERIMENTS_REGISTRY
+
+
+def initialize_environment(
+    path: str | Path = ".", name: str | None = None
+) -> Environment:
+    """Create the standard Researchium structure and register the directory.
+
+    Args:
+        path: Directory to initialize. Created if it does not exist.
+        name: Environment name. Defaults to the directory's basename.
+
+    Returns:
+        The newly created ``Environment``.
+
+    Raises:
+        EnvironmentExistsError: If ``path`` is already a Researchium environment.
+    """
+    root = Path(path).resolve()
+    if (root / MARKER_DIR_NAME).exists():
+        raise EnvironmentExistsError(f"{root} is already a Researchium environment.")
+
+    experiments = root / "experiments"
+    src = root / "src"
+    results = root / "results"
+
+    experiments.mkdir(parents=True, exist_ok=True)
+    src.mkdir(parents=True, exist_ok=True)
+    results.mkdir(parents=True, exist_ok=True)
+
+    _write_experiments_notebook(root, name)
+    _write_experiments_registry(root)
+    marker = _write_marker(root, name)
+
+    return _load_environment(marker)
+
+
+def is_initialized(path: str | Path = ".") -> bool:
+    """Return ``True`` if ``path`` is directly an initialized environment."""
+    return (Path(path).resolve() / MARKER_DIR_NAME).is_dir()
+
+
+def discover_environment(path: str | Path = ".") -> Environment:
+    """Return the nearest environment at ``path``, walking up parent directories.
+
+    Raises:
+        EnvironmentNotFoundError: If no ancestor directory is initialized.
+    """
+    start = Path(path).resolve()
+    for current in (start, *start.parents):
+        marker = current / MARKER_DIR_NAME
+        if marker.is_dir():
+            return _load_environment(marker)
+    raise EnvironmentNotFoundError(
+        f"No Researchium environment found at or above {start}. "
+        f"Run `researchium init` to create one."
+    )
+
+
+def _write_experiments_notebook(root: Path, name: str | None) -> None:
+    created = date.today()
+    header = name or root.name
+    content = (
+        f"# {header}\n"
+        "\n"
+        "Researchium environment initialized on "
+        f"{created.isoformat()}.\n"
+        "\n"
+        "## Experiments\n"
+        "\n"
+        "Each experiment has a folder in `experiments/` and a section below.\n"
+    )
+    (root / EXPERIMENTS_NOTEBOOK).write_text(content, encoding="utf-8")
+
+
+def load_experiments_registry(path: str | Path) -> list[dict]:
+    """Load experiment metadata records from ``path`` (empty list if absent)."""
+    registry = Path(path)
+    if not registry.exists():
+        return []
+    data = json.loads(registry.read_text(encoding="utf-8"))
+    return data["experiments"]
+
+
+def save_experiments_registry(path: str | Path, experiments: list[dict]) -> None:
+    """Write experiment metadata records to ``path``."""
+    data = {"version": REGISTRY_VERSION, "experiments": experiments}
+    Path(path).write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _write_experiments_registry(root: Path) -> None:
+    save_experiments_registry(root / EXPERIMENTS_REGISTRY, [])
+
+
+def _write_marker(root: Path, name: str | None) -> Path:
+    marker = root / MARKER_DIR_NAME
+    marker.mkdir(parents=True, exist_ok=True)
+    metadata = {
+        "name": name or root.name,
+        "created": date.today().isoformat(),
+        "researchium": researchium.__version__,
+    }
+    (marker / METADATA_FILE_NAME).write_text(
+        json.dumps(metadata, indent=2) + "\n", encoding="utf-8"
+    )
+    return marker
+
+
+def _load_environment(marker: Path) -> Environment:
+    metadata = json.loads((marker / METADATA_FILE_NAME).read_text(encoding="utf-8"))
+    return Environment(
+        root=marker.parent,
+        name=metadata["name"],
+        created=date.fromisoformat(metadata["created"]),
+        researchium_version=metadata["researchium"],
+    )

researchium/experiments.py

@@ -0,0 +1,213 @@
+"""Experiment management inside a Researchium environment."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+from researchium.environment import (
+    Environment,
+    ResearchiumError,
+    discover_environment,
+    load_experiments_registry,
+    save_experiments_registry,
+)
+
+
+class ExperimentExistsError(ResearchiumError):
+    """Raised when an experiment name is already in use."""
+
+
+class InvalidExperimentNameError(ResearchiumError):
+    """Raised when an experiment name is not a safe folder name."""
+
+
+class ExperimentNotFoundError(ResearchiumError):
+    """Raised when no experiment matches a given ID or name."""
+
+
+@dataclass(frozen=True)
+class Experiment:
+    """A single experiment living inside an environment's experiments folder."""
+
+    id: str
+    name: str
+    description: str
+    created: date
+    environment: Environment
+
+    @property
+    def path(self) -> Path:
+        return self.environment.experiments_dir / self.name
+
+    @property
+    def results_dir(self) -> Path:
+        return self.environment.results_dir / self.name
+
+    def to_metadata(self) -> dict:
+        """Return the record stored in ``experiments.json``."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "created": self.created.isoformat(),
+        }
+
+
+def create_experiment(
+    name: str, description: str, path: str | Path = "."
+) -> Experiment:
+    """Create an experiment folder and log it in the experiments notebook.
+
+    Args:
+        name: Experiment name, also used as the folder name.
+        description: Brief description logged in ``experiments.md``.
+        path: Where to start looking for the environment. Defaults to the
+            current directory and walks up from there.
+
+    Returns:
+        The created ``Experiment``.
+
+    Raises:
+        EnvironmentNotFoundError: If no environment is found at ``path``.
+        InvalidExperimentNameError: If ``name`` is empty or a path separator.
+        ExperimentExistsError: If the experiment folder or notebook entry
+            already exists.
+    """
+    env = discover_environment(path)
+    _validate_name(name)
+
+    folder = env.experiments_dir / name
+    if folder.exists():
+        raise ExperimentExistsError(f"Experiment {name!r} already exists at {folder}.")
+    if _has_notebook_entry(env.experiments_notebook, name):
+        raise ExperimentExistsError(
+            f"Experiment {name!r} is already logged in the experiments notebook."
+        )
+
+    created = date.today()
+    experiment = Experiment(
+        id=_generate_id(),
+        name=name,
+        description=description,
+        created=created,
+        environment=env,
+    )
+    folder.mkdir()
+    experiment.results_dir.mkdir(parents=True)
+    _append_notebook_entry(
+        env.experiments_notebook, experiment.id, name, description, created
+    )
+    _add_to_registry(env, experiment)
+
+    return experiment
+
+
+def list_experiments(path: str | Path = ".") -> list[Experiment]:
+    """Return all experiments in the environment at ``path``, sorted by name."""
+    env = discover_environment(path)
+    records = load_experiments_registry(env.experiments_registry)
+    experiments = [_experiment_from_record(env, record) for record in records]
+    return sorted(experiments, key=lambda experiment: experiment.name)
+
+
+def search_experiments(query: str, path: str | Path = ".") -> list[Experiment]:
+    """Return experiments whose name or description contains ``query``."""
+    needle = query.strip().lower()
+    if not needle:
+        return []
+    return [
+        experiment
+        for experiment in list_experiments(path)
+        if needle in experiment.name.lower()
+        or needle in experiment.description.lower()
+    ]
+
+
+def get_experiment(identifier: str, path: str | Path = ".") -> Experiment:
+    """Return the experiment registered under an ID or name.
+
+    IDs are checked first, then names (case-insensitive).
+
+    Raises:
+        ExperimentNotFoundError: If no experiment matches ``identifier``.
+    """
+    experiments = list_experiments(path)
+    for experiment in experiments:
+        if experiment.id == identifier:
+            return experiment
+    for experiment in experiments:
+        if experiment.name.lower() == identifier.lower():
+            return experiment
+    raise ExperimentNotFoundError(
+        f"No experiment with ID or name {identifier!r}."
+    )
+
+
+def get_experiment_results(
+    identifier: str, path: str | Path = "."
+) -> list[Path]:
+    """Return the result files of an experiment, sorted by name.
+
+    ``identifier`` may be an experiment ID or name.
+    """
+    experiment = get_experiment(identifier, path)
+    results = experiment.results_dir
+    if not results.is_dir():
+        return []
+    return sorted(path for path in results.iterdir() if path.is_file())
+
+
+def _experiment_from_record(env: Environment, record: dict) -> Experiment:
+    return Experiment(
+        id=record["id"],
+        name=record["name"],
+        description=record["description"],
+        created=date.fromisoformat(record["created"]),
+        environment=env,
+    )
+
+
+def _generate_id() -> str:
+    return uuid.uuid4().hex[:8]
+
+
+def _validate_name(name: str) -> None:
+    if not name or name.strip() in {".", ".."}:
+        raise InvalidExperimentNameError("Experiment name may not be empty.")
+    if "/" in name or "\\" in name:
+        raise InvalidExperimentNameError(
+            "Experiment name may not contain path separators."
+        )
+
+
+def _has_notebook_entry(notebook: Path, name: str) -> bool:
+    if not notebook.exists():
+        return False
+    text = notebook.read_text(encoding="utf-8")
+    return re.search(rf"^### {re.escape(name)}\s*$", text, re.MULTILINE) is not None
+
+
+def _append_notebook_entry(
+    notebook: Path, experiment_id: str, name: str, description: str, created: date
+) -> None:
+    entry = (
+        f"\n### {name}\n"
+        f"\n"
+        f"{description}\n"
+        f"\n"
+        f"- ID: `{experiment_id}`\n"
+        f"- Created: {created.isoformat()}\n"
+        f"- Folder: `experiments/{name}`\n"
+    )
+    with notebook.open("a", encoding="utf-8") as handle:
+        handle.write(entry)
+
+
+def _add_to_registry(env: Environment, experiment: Experiment) -> None:
+    experiments = load_experiments_registry(env.experiments_registry)
+    experiments.append(experiment.to_metadata())
+    save_experiments_registry(env.experiments_registry, experiments)

researchium/runtime.py

@@ -0,0 +1,182 @@
+"""Ephemeral run-time registries and the experiment runner."""
+
+from __future__ import annotations
+
+import json
+import runpy
+from datetime import datetime
+from pathlib import Path
+
+from researchium.environment import ResearchiumError
+from researchium.experiments import Experiment, get_experiment
+
+
+class RunScriptNotFoundError(ResearchiumError):
+    """Raised when an experiment has no run script."""
+
+
+class RunFailedError(ResearchiumError):
+    """Raised when an experiment's run script raises."""
+
+
+class RunStorage(dict):
+    """Mutable registry that a run script fills in at runtime."""
+
+
+Config = RunStorage()
+Results = RunStorage()
+
+
+def run_experiment(identifier: str, path: str | Path = ".") -> Experiment:
+    """Execute an experiment's run script and persist its config and results.
+
+    Runs ``experiments/<name>/run.py`` with a fresh ``Config``/``Results``,
+    then writes:
+
+    - ``experiments/<name>/config.md`` / ``config.json``
+    - ``results/<name>/results.md`` / ``results.json``
+
+    Args:
+        identifier: Experiment ID or name.
+        path: Where to start looking for the environment.
+
+    Returns:
+        The executed ``Experiment``.
+
+    Raises:
+        RunScriptNotFoundError: If the experiment has no ``run.py``.
+        RunFailedError: If the run script raises.
+    """
+    experiment = get_experiment(identifier, path)
+    script = experiment.path / "run.py"
+    if not script.is_file():
+        raise RunScriptNotFoundError(
+            f"Experiment {experiment.name!r} has no run script at {script}. "
+            f"Create experiments/{experiment.name}/run.py first."
+        )
+
+    Config.clear()
+    Results.clear()
+    try:
+        runpy.run_path(str(script), run_name="__main__")
+    except Exception as exc:
+        raise RunFailedError(
+            f"Experiment {experiment.name!r} failed during run: {exc}"
+        ) from exc
+
+    write_run_outputs(experiment)
+    return experiment
+
+
+def write_run_outputs(experiment: Experiment) -> list[Path]:
+    """Write the current ``Config``/``Results`` for an experiment to disk."""
+    run_at = datetime.now().strftime("%Y-%m-%d %H:%M")
+    config_md = experiment.path / "config.md"
+    config_md.write_text(
+        _format_document(experiment, "Configuration", Config, run_at),
+        encoding="utf-8",
+    )
+
+    experiment.results_dir.mkdir(parents=True, exist_ok=True)
+    results_md = experiment.results_dir / "results.md"
+    results_md.write_text(
+        _format_document(experiment, "Results", Results, run_at),
+        encoding="utf-8",
+    )
+
+    _remove_stale_readme(experiment)
+    _write_json(experiment.path / "config.json", Config)
+    _write_json(experiment.results_dir / "results.json", Results)
+
+    return [
+        config_md,
+        experiment.path / "config.json",
+        results_md,
+        experiment.results_dir / "results.json",
+    ]
+
+
+def format_configuration(identifier: str, path: str | Path = ".") -> str:
+    """Return an experiment's configuration as ``key: value`` lines."""
+    experiment = get_experiment(identifier, path)
+    config_json = experiment.path / "config.json"
+    if not config_json.is_file():
+        return "(no configuration yet)"
+    records = json.loads(config_json.read_text(encoding="utf-8"))
+    return _format_key_values(records)
+
+
+def format_run_results(identifier: str, path: str | Path = ".") -> str:
+    """Return an experiment's results as ``key: value`` lines.
+
+    Falls back to a file listing when the experiment has no ``results.json``.
+    """
+    experiment = get_experiment(identifier, path)
+    results_json = experiment.results_dir / "results.json"
+    if results_json.is_file():
+        records = json.loads(results_json.read_text(encoding="utf-8"))
+        return _format_key_values(records)
+    return _format_results_listing(experiment)
+
+
+def _format_key_values(records: dict) -> str:
+    if not records:
+        return "(none)"
+    return "\n".join(
+        f"{key}: {_inline(value)}" for key, value in records.items()
+    )
+
+
+def _format_document(
+    experiment: Experiment, title: str, registry: RunStorage, run_at: str
+) -> str:
+    lines = [f"# {experiment.name}", "", f"Last run: {run_at}", "", f"## {title}", ""]
+    if not registry:
+        lines.append("(none)")
+    for key, value in registry.items():
+        lines.append(f"- **{key}**: {_inline(value)}")
+    return "\n".join(lines) + "\n"
+
+
+def _format_results_listing(experiment: Experiment) -> str:
+    results_dir = experiment.results_dir
+    lines = [
+        f"Experiment: {experiment.name} (ID {experiment.id})",
+        f"Results ({results_dir}):",
+    ]
+    if results_dir.is_dir():
+        results = sorted(path for path in results_dir.iterdir() if path.is_file())
+    else:
+        results = []
+    if not results:
+        lines.append("  (no results yet)")
+        return "\n".join(lines)
+    for result in results:
+        lines.append(f"  - {result.name}  ({_format_size(result.stat().st_size)})")
+    return "\n".join(lines)
+
+
+def _inline(value: object) -> str:
+    if isinstance(value, (dict, list, tuple)):
+        return json.dumps(value)
+    return str(value)
+
+
+def _format_size(num_bytes: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if num_bytes < 1024:
+            return f"{num_bytes:.0f} {unit}"
+        num_bytes /= 1024
+    return f"{num_bytes:.1f} TB"
+
+
+def _write_json(path: Path, storage: RunStorage) -> None:
+    path.write_text(
+        json.dumps(storage, indent=2, default=str) + "\n", encoding="utf-8"
+    )
+
+
+def _remove_stale_readme(experiment: Experiment) -> None:
+    readme = experiment.path / "readme.md"
+    if readme.exists():
+        readme.unlink()

researchium-0.1.0.dist-info/METADATA

@@ -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.

researchium-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+researchium/__init__.py,sha256=Ezle8dFpjtZwLU3J2ElpOCKJG4PZKOMyCLHqcunaEos,1355
+researchium/cli.py,sha256=J86DS3nniDQ5l_TJXKW_D2W7jfIGa3TGan2t4_pr0bM,3541
+researchium/environment.py,sha256=mTZaKpnLD3grVndebWKp8CmWlXNDfvkJveCgPvJsKrs,5452
+researchium/experiments.py,sha256=HN6ubISfspMDY9rcKIWAXC4OH8i76_Wy63_GyMG2zdE,6533
+researchium/runtime.py,sha256=8XidorLPSm8-ZMrynXczY61ER8XHSzwiMh04MKNayYM,5640
+researchium-0.1.0.dist-info/METADATA,sha256=pPAIq6I0JmszhRL4XYAM-QVQd1SKxPAWMXclLkvQkHM,16888
+researchium-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+researchium-0.1.0.dist-info/entry_points.txt,sha256=PT99_EpSMwl7LknsaCM9Pb8Y7gL18PKVT1vkdsL08qE,53
+researchium-0.1.0.dist-info/licenses/LICENSE,sha256=yuK449AmmLkXdEuSVgJdmIxrqdTaygTEs7XrWGVKE_8,1071
+researchium-0.1.0.dist-info/RECORD,,

researchium-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

researchium-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+researchium = researchium.cli:main

researchium-0.1.0.dist-info/licenses/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.