talosdb 0.1.0__tar.gz

talosdb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GrindelfP
+
+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.

talosdb-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: talosdb
+Version: 0.1.0
+Summary: Lightweight experiment storage library for scientific simulations.
+Author-email: GrindelfP <grindelf.perlomutrovij@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/GrindelfP/talosdb
+Project-URL: Repository, https://github.com/GrindelfP/talosdb
+Project-URL: Bug Tracker, https://github.com/GrindelfP/talosdb/issues
+Keywords: experiment,simulation,storage,science,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# talosdb
+
+Lightweight experiment storage library for scientific simulations.
+Named after Talos I station.
+
+## Installation
+
+```bash
+pip install src
+```
+
+## Quickstart
+
+```python
+from src import TalosDB
+from itertools import product
+
+db = TalosDB("~/science/results")
+exp = db.experiment("vc_sweep_2025")
+
+A_grid = [0.5, 1.0, 1.5]
+beta_grid = [1.0, 2.0]
+
+for A, beta in product(A_grid, beta_grid):
+    result = simulate(A, beta)  # numpy array
+    with exp.run({"A": A, "beta": beta}) as run:
+        run.save(result)
+        run.save_params({"gamma": 0.1, "T": 300})  # extra constants
+        run.save_plot(my_plot_fn, result)
+```
+
+## File layout
+
+```
+db_root/
+└── vc_sweep_2025/
+    ├── experiment.json          # metadata: name, creation date
+    ├── A=0.5_beta=1.0/
+    │   ├── data.dat             # human-readable TSV (numpy array)
+    │   ├── params.json          # all parameters (name + extra)
+    │   └── plot.png             # if save_plot() was called
+    └── A=1.0_beta=2.0/
+        ├── data.dat
+        └── params.json
+```
+
+## API reference
+
+### TalosDB
+
+```python
+db = TalosDB("path/to/db")        # creates root folder if absent
+db.experiment("name")              # create / open experiment
+db.experiment()                    # name = datetime stamp
+db.list_experiments()              # → list[str]
+db.delete_experiment("name", confirm=True)
+```
+
+### Experiment
+
+```python
+exp = db.experiment("my_exp")
+
+# Create / open a run
+run  = exp.run({"A": 0.5, "beta": 1.0})
+# or as context manager (marks failed.json on exception):
+with exp.run({"A": 0.5, "beta": 1.0}) as run:
+    ...
+
+# Load
+run  = exp.load({"A": 0.5, "beta": 1.0})   # exact match
+runs = exp.query({"beta": 1.0})             # subset match → list[Run]
+runs = exp.all_runs()                        # every run
+```
+
+### Run
+
+```python
+run.save(result)                            # numpy array → data.dat
+run.save_params({"gamma": 0.1, "T": 300})  # extra params → params.json
+run.save_plot(plot_fn, result)              # calls plot_fn(result, path)
+
+result = run.load_data()                    # → np.ndarray
+params = run.load_params()                  # → dict
+run.is_failed()                             # → bool
+run.load_failure()                          # → dict with error info
+```
+
+### plot_fn contract
+
+```python
+def my_plot_fn(result, save_path):
+    fig, ax = plt.subplots()
+    ax.plot(result[:, 0], result[:, 1])
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+talosdb does not import matplotlib — rendering is entirely the caller's responsibility.
+
+## .dat format
+
+Arrays are stored as human-readable TSV with a small header:
+
+```
+# shape: 100 2
+# dtype: float64
+0.0	0.001
+0.1	0.043
+...
+```
+
+3D+ arrays are split into labelled 2D slices:
+
+```
+# shape: 2 3 4
+# dtype: float64
+# slice [0]
+1.0	2.0	3.0	4.0
+5.0	6.0	7.0	8.0
+9.0	10.0	11.0	12.0
+
+# slice [1]
+...
+```
+
+The shape header ensures exact reconstruction on load regardless of dimensionality.
+
+## License
+
+MIT

talosdb-0.1.0/README.md

@@ -0,0 +1,131 @@
+# talosdb
+
+Lightweight experiment storage library for scientific simulations.
+Named after Talos I station.
+
+## Installation
+
+```bash
+pip install src
+```
+
+## Quickstart
+
+```python
+from src import TalosDB
+from itertools import product
+
+db = TalosDB("~/science/results")
+exp = db.experiment("vc_sweep_2025")
+
+A_grid = [0.5, 1.0, 1.5]
+beta_grid = [1.0, 2.0]
+
+for A, beta in product(A_grid, beta_grid):
+    result = simulate(A, beta)  # numpy array
+    with exp.run({"A": A, "beta": beta}) as run:
+        run.save(result)
+        run.save_params({"gamma": 0.1, "T": 300})  # extra constants
+        run.save_plot(my_plot_fn, result)
+```
+
+## File layout
+
+```
+db_root/
+└── vc_sweep_2025/
+    ├── experiment.json          # metadata: name, creation date
+    ├── A=0.5_beta=1.0/
+    │   ├── data.dat             # human-readable TSV (numpy array)
+    │   ├── params.json          # all parameters (name + extra)
+    │   └── plot.png             # if save_plot() was called
+    └── A=1.0_beta=2.0/
+        ├── data.dat
+        └── params.json
+```
+
+## API reference
+
+### TalosDB
+
+```python
+db = TalosDB("path/to/db")        # creates root folder if absent
+db.experiment("name")              # create / open experiment
+db.experiment()                    # name = datetime stamp
+db.list_experiments()              # → list[str]
+db.delete_experiment("name", confirm=True)
+```
+
+### Experiment
+
+```python
+exp = db.experiment("my_exp")
+
+# Create / open a run
+run  = exp.run({"A": 0.5, "beta": 1.0})
+# or as context manager (marks failed.json on exception):
+with exp.run({"A": 0.5, "beta": 1.0}) as run:
+    ...
+
+# Load
+run  = exp.load({"A": 0.5, "beta": 1.0})   # exact match
+runs = exp.query({"beta": 1.0})             # subset match → list[Run]
+runs = exp.all_runs()                        # every run
+```
+
+### Run
+
+```python
+run.save(result)                            # numpy array → data.dat
+run.save_params({"gamma": 0.1, "T": 300})  # extra params → params.json
+run.save_plot(plot_fn, result)              # calls plot_fn(result, path)
+
+result = run.load_data()                    # → np.ndarray
+params = run.load_params()                  # → dict
+run.is_failed()                             # → bool
+run.load_failure()                          # → dict with error info
+```
+
+### plot_fn contract
+
+```python
+def my_plot_fn(result, save_path):
+    fig, ax = plt.subplots()
+    ax.plot(result[:, 0], result[:, 1])
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+talosdb does not import matplotlib — rendering is entirely the caller's responsibility.
+
+## .dat format
+
+Arrays are stored as human-readable TSV with a small header:
+
+```
+# shape: 100 2
+# dtype: float64
+0.0	0.001
+0.1	0.043
+...
+```
+
+3D+ arrays are split into labelled 2D slices:
+
+```
+# shape: 2 3 4
+# dtype: float64
+# slice [0]
+1.0	2.0	3.0	4.0
+5.0	6.0	7.0	8.0
+9.0	10.0	11.0	12.0
+
+# slice [1]
+...
+```
+
+The shape header ensures exact reconstruction on load regardless of dimensionality.
+
+## License
+
+MIT

talosdb-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+
+[project]
+name = "talosdb"
+version = "0.1.0"
+description = "Lightweight experiment storage library for scientific simulations."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "GrindelfP", email = "grindelf.perlomutrovij@gmail.com" },
+]
+keywords = ["experiment", "simulation", "storage", "science", "numpy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[project.urls]
+Homepage = "https://github.com/GrindelfP/talosdb"
+Repository = "https://github.com/GrindelfP/talosdb"
+"Bug Tracker" = "https://github.com/GrindelfP/talosdb/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

talosdb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

talosdb-0.1.0/src/talosdb.egg-info/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: talosdb
+Version: 0.1.0
+Summary: Lightweight experiment storage library for scientific simulations.
+Author-email: GrindelfP <grindelf.perlomutrovij@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/GrindelfP/talosdb
+Project-URL: Repository, https://github.com/GrindelfP/talosdb
+Project-URL: Bug Tracker, https://github.com/GrindelfP/talosdb/issues
+Keywords: experiment,simulation,storage,science,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# talosdb
+
+Lightweight experiment storage library for scientific simulations.
+Named after Talos I station.
+
+## Installation
+
+```bash
+pip install src
+```
+
+## Quickstart
+
+```python
+from src import TalosDB
+from itertools import product
+
+db = TalosDB("~/science/results")
+exp = db.experiment("vc_sweep_2025")
+
+A_grid = [0.5, 1.0, 1.5]
+beta_grid = [1.0, 2.0]
+
+for A, beta in product(A_grid, beta_grid):
+    result = simulate(A, beta)  # numpy array
+    with exp.run({"A": A, "beta": beta}) as run:
+        run.save(result)
+        run.save_params({"gamma": 0.1, "T": 300})  # extra constants
+        run.save_plot(my_plot_fn, result)
+```
+
+## File layout
+
+```
+db_root/
+└── vc_sweep_2025/
+    ├── experiment.json          # metadata: name, creation date
+    ├── A=0.5_beta=1.0/
+    │   ├── data.dat             # human-readable TSV (numpy array)
+    │   ├── params.json          # all parameters (name + extra)
+    │   └── plot.png             # if save_plot() was called
+    └── A=1.0_beta=2.0/
+        ├── data.dat
+        └── params.json
+```
+
+## API reference
+
+### TalosDB
+
+```python
+db = TalosDB("path/to/db")        # creates root folder if absent
+db.experiment("name")              # create / open experiment
+db.experiment()                    # name = datetime stamp
+db.list_experiments()              # → list[str]
+db.delete_experiment("name", confirm=True)
+```
+
+### Experiment
+
+```python
+exp = db.experiment("my_exp")
+
+# Create / open a run
+run  = exp.run({"A": 0.5, "beta": 1.0})
+# or as context manager (marks failed.json on exception):
+with exp.run({"A": 0.5, "beta": 1.0}) as run:
+    ...
+
+# Load
+run  = exp.load({"A": 0.5, "beta": 1.0})   # exact match
+runs = exp.query({"beta": 1.0})             # subset match → list[Run]
+runs = exp.all_runs()                        # every run
+```
+
+### Run
+
+```python
+run.save(result)                            # numpy array → data.dat
+run.save_params({"gamma": 0.1, "T": 300})  # extra params → params.json
+run.save_plot(plot_fn, result)              # calls plot_fn(result, path)
+
+result = run.load_data()                    # → np.ndarray
+params = run.load_params()                  # → dict
+run.is_failed()                             # → bool
+run.load_failure()                          # → dict with error info
+```
+
+### plot_fn contract
+
+```python
+def my_plot_fn(result, save_path):
+    fig, ax = plt.subplots()
+    ax.plot(result[:, 0], result[:, 1])
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+talosdb does not import matplotlib — rendering is entirely the caller's responsibility.
+
+## .dat format
+
+Arrays are stored as human-readable TSV with a small header:
+
+```
+# shape: 100 2
+# dtype: float64
+0.0	0.001
+0.1	0.043
+...
+```
+
+3D+ arrays are split into labelled 2D slices:
+
+```
+# shape: 2 3 4
+# dtype: float64
+# slice [0]
+1.0	2.0	3.0	4.0
+5.0	6.0	7.0	8.0
+9.0	10.0	11.0	12.0
+
+# slice [1]
+...
+```
+
+The shape header ensures exact reconstruction on load regardless of dimensionality.
+
+## License
+
+MIT

talosdb-0.1.0/src/talosdb.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/talosdb.egg-info/PKG-INFO
+src/talosdb.egg-info/SOURCES.txt
+src/talosdb.egg-info/dependency_links.txt
+src/talosdb.egg-info/requires.txt
+src/talosdb.egg-info/top_level.txt
+tests/test_talosdb.py

talosdb-0.1.0/src/talosdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

talosdb-0.1.0/src/talosdb.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy>=1.24
+
+[dev]
+pytest>=7.0
+pytest-cov

talosdb-0.1.0/src/talosdb.egg-info/top_level.txt

@@ -0,0 +1 @@
+

talosdb-0.1.0/tests/test_talosdb.py

@@ -0,0 +1,299 @@
+"""
+Tests for src.
+"""
+import json
+import math
+import warnings
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from src import TalosDB, Experiment, Run
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def db(tmp_path):
+    return TalosDB(tmp_path / "testdb")
+
+
+@pytest.fixture
+def exp(db):
+    return db.experiment("test_exp")
+
+
+# ---------------------------------------------------------------------------
+# _params_to_dirname / _dirname_to_params round-trip
+# ---------------------------------------------------------------------------
+
+class TestDirnameParsing:
+    def test_basic_roundtrip(self):
+        from src import _params_to_dirname, _dirname_to_params
+        params = {"A": 0.5, "beta": 1.0}
+        assert _dirname_to_params(_params_to_dirname(params)) == params
+
+    def test_int_value(self):
+        from src import _params_to_dirname, _dirname_to_params
+        params = {"N": 100, "mode": 2}
+        result = _dirname_to_params(_params_to_dirname(params))
+        assert result == params
+
+    def test_string_value(self):
+        from src import _params_to_dirname, _dirname_to_params
+        params = {"solver": "euler", "A": 1.0}
+        result = _dirname_to_params(_params_to_dirname(params))
+        assert result == params
+
+    def test_underscore_in_value(self):
+        """Values containing underscores must not confuse the parser."""
+        from src import _params_to_dirname, _dirname_to_params
+        params = {"method": "runge_kutta", "A": 0.5}
+        dirname = _params_to_dirname(params)
+        parsed  = _dirname_to_params(dirname)
+        assert parsed["method"] == "runge_kutta"
+        assert math.isclose(parsed["A"], 0.5)
+
+    def test_sorted_keys(self):
+        from src import _params_to_dirname
+        d1 = _params_to_dirname({"beta": 1.0, "A": 0.5})
+        d2 = _params_to_dirname({"A": 0.5, "beta": 1.0})
+        assert d1 == d2
+
+
+# ---------------------------------------------------------------------------
+# .dat round-trip
+# ---------------------------------------------------------------------------
+
+class TestDatFormat:
+    def _roundtrip(self, arr, tmp_path):
+        from src import _save_dat, _load_dat
+        p = tmp_path / "test.dat"
+        _save_dat(p, arr)
+        return _load_dat(p)
+
+    def test_1d(self, tmp_path):
+        arr = np.linspace(0, 1, 50)
+        result = self._roundtrip(arr, tmp_path)
+        assert result.shape == arr.shape
+        np.testing.assert_array_almost_equal(result, arr)
+
+    def test_2d(self, tmp_path):
+        arr = np.random.rand(20, 3)
+        result = self._roundtrip(arr, tmp_path)
+        assert result.shape == arr.shape
+        np.testing.assert_array_almost_equal(result, arr)
+
+    def test_3d(self, tmp_path):
+        arr = np.random.rand(4, 5, 6)
+        result = self._roundtrip(arr, tmp_path)
+        assert result.shape == arr.shape
+        np.testing.assert_array_almost_equal(result, arr)
+
+    def test_4d(self, tmp_path):
+        arr = np.arange(2 * 3 * 4 * 5, dtype=float).reshape(2, 3, 4, 5)
+        result = self._roundtrip(arr, tmp_path)
+        assert result.shape == arr.shape
+        np.testing.assert_array_equal(result, arr)
+
+    def test_human_readable(self, tmp_path):
+        """The .dat file must be readable as plain text."""
+        from src import _save_dat
+        arr = np.array([[1.0, 2.0], [3.0, 4.0]])
+        p = tmp_path / "test.dat"
+        _save_dat(p, arr)
+        text = p.read_text()
+        assert "# shape:" in text
+        assert "# dtype:" in text
+        assert "1.0\t2.0" in text
+
+    def test_integer_dtype(self, tmp_path):
+        arr = np.array([1, 2, 3, 4, 5], dtype=np.int32)
+        result = self._roundtrip(arr, tmp_path)
+        assert result.dtype == arr.dtype
+        np.testing.assert_array_equal(result, arr)
+
+
+# ---------------------------------------------------------------------------
+# Run
+# ---------------------------------------------------------------------------
+
+class TestRun:
+    def test_save_and_load_data(self, exp):
+        run = exp.run({"A": 0.5, "beta": 1.0})
+        data = np.random.rand(10, 2)
+        run.save(data)
+        loaded = run.load_data()
+        np.testing.assert_array_almost_equal(loaded, data)
+
+    def test_save_params_merges(self, exp):
+        run = exp.run({"A": 0.5, "beta": 1.0})
+        run.save_params({"gamma": 0.1, "T": 300})
+        params = run.load_params()
+        assert params["A"] == 0.5
+        assert params["beta"] == 1.0
+        assert params["gamma"] == 0.1
+        assert params["T"] == 300
+
+    def test_save_params_no_extra(self, exp):
+        run = exp.run({"A": 1.0})
+        run.save_params()
+        params = run.load_params()
+        assert params == {"A": 1.0}
+
+    def test_save_plot(self, exp, tmp_path):
+        run = exp.run({"A": 0.5})
+        data = np.eye(3)
+        saved_paths = []
+
+        def fake_plot(result, save_path):
+            save_path = Path(save_path)
+            save_path.write_text("fake_image")
+            saved_paths.append(save_path)
+
+        run.save_plot(fake_plot, data)
+        assert len(saved_paths) == 1
+        assert saved_paths[0].exists()
+
+    def test_load_data_missing_raises(self, exp):
+        run = exp.run({"A": 99.0})
+        with pytest.raises(FileNotFoundError):
+            run.load_data()
+
+    def test_load_params_missing_raises(self, exp):
+        run = exp.run({"A": 99.0})
+        with pytest.raises(FileNotFoundError):
+            run.load_params()
+
+    def test_context_manager_success(self, exp):
+        data = np.arange(5, dtype=float)
+        with exp.run({"A": 1.0}) as run:
+            run.save(data)
+        assert not run.is_failed()
+
+    def test_context_manager_failure(self, exp):
+        with pytest.raises(RuntimeError):
+            with exp.run({"A": 2.0}) as run:
+                raise RuntimeError("simulation exploded")
+        assert run.is_failed()
+        info = run.load_failure()
+        assert info["error"] == "RuntimeError"
+        assert "simulation exploded" in info["message"]
+
+    def test_is_failed_false_by_default(self, exp):
+        run = exp.run({"A": 3.0})
+        assert not run.is_failed()
+
+    def test_overwrite_warning(self, exp):
+        exp.run({"A": 0.5, "beta": 1.0})
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            exp.run({"A": 0.5, "beta": 1.0})
+            assert len(w) == 1
+            assert "already exists" in str(w[0].message)
+
+    def test_overwrite_no_warning(self, exp):
+        exp.run({"A": 0.5, "beta": 1.0})
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            exp.run({"A": 0.5, "beta": 1.0}, overwrite=True)
+            assert len(w) == 0
+
+
+# ---------------------------------------------------------------------------
+# Experiment
+# ---------------------------------------------------------------------------
+
+class TestExperiment:
+    def test_name(self, exp):
+        assert exp.name == "test_exp"
+
+    def test_meta_file_created(self, exp):
+        assert (exp.path / "experiment.json").exists()
+
+    def test_load_exact(self, exp):
+        params = {"A": 0.5, "beta": 1.0}
+        run = exp.run(params)
+        run.save_params()
+        loaded = exp.load(params)
+        assert loaded.path == run.path
+
+    def test_load_missing_raises(self, exp):
+        with pytest.raises(FileNotFoundError):
+            exp.load({"A": 999.0})
+
+    def test_query_subset(self, exp):
+        for beta in [1.0, 2.0]:
+            for A in [0.5, 1.0]:
+                r = exp.run({"A": A, "beta": beta})
+                r.save_params()
+        results = exp.query({"beta": 1.0})
+        assert len(results) == 2
+        assert all(r.load_params()["beta"] == 1.0 for r in results)
+
+    def test_query_no_match(self, exp):
+        exp.run({"A": 0.5}).save_params()
+        assert exp.query({"A": 999.0}) == []
+
+    def test_all_runs(self, exp):
+        for i in range(3):
+            exp.run({"i": i}).save_params()
+        runs = exp.all_runs()
+        assert len(runs) == 3
+
+    def test_repr(self, exp):
+        assert "test_exp" in repr(exp)
+
+
+# ---------------------------------------------------------------------------
+# TalosDB
+# ---------------------------------------------------------------------------
+
+class TestTalosDB:
+    def test_creates_directory(self, tmp_path):
+        path = tmp_path / "newdb"
+        db = TalosDB(path)
+        assert db.path.exists()
+
+    def test_experiment_creates_subdir(self, db):
+        exp = db.experiment("alpha")
+        assert (db.path / "alpha").is_dir()
+
+    def test_experiment_auto_name(self, db):
+        exp = db.experiment()
+        assert exp.path.exists()
+
+    def test_list_experiments(self, db):
+        db.experiment("a")
+        db.experiment("b")
+        db.experiment("c")
+        names = db.list_experiments()
+        assert "a" in names
+        assert "b" in names
+        assert "c" in names
+
+    def test_delete_experiment_requires_confirm(self, db):
+        db.experiment("to_delete")
+        with pytest.raises(ValueError, match="confirm=True"):
+            db.delete_experiment("to_delete")
+
+    def test_delete_experiment(self, db):
+        db.experiment("to_delete")
+        db.delete_experiment("to_delete", confirm=True)
+        assert "to_delete" not in db.list_experiments()
+
+    def test_delete_experiment_missing_raises(self, db):
+        with pytest.raises(FileNotFoundError):
+            db.delete_experiment("ghost", confirm=True)
+
+    def test_tilde_expansion(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        db = TalosDB("~/mydb")
+        assert db.path.exists()
+        assert str(tmp_path) in str(db.path)
+
+    def test_repr(self, db):
+        assert "TalosDB" in repr(db)