evalstone 0.1.0__tar.gz

evalstone-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# ── Secrets / local env ────────────────────────────────────────────────
+**/.env
+**/.env.local
+**/.env.*.local
+**/.env.production
+!**/.env.example
+
+# ── OS / editor ────────────────────────────────────────────────────────
+.DS_Store
+*.pem
+*.swp
+*~
+**/certs/
+
+# ── Python (python/) ───────────────────────────────────────────────────
+**/venv/
+**/.venv/
+**/__pycache__/
+*.pyc
+**/.pytest_cache/
+**/.ruff_cache/
+**/.mypy_cache/
+*.egg-info/
+**/dist/
+.coverage
+htmlcov/
+
+# ── Node / Next.js (javascript/) ───────────────────────────────────────
+**/node_modules/
+**/.next/
+**/.source/
+**/out/
+**/build/
+**/coverage/
+*.tsbuildinfo
+next-env.d.ts
+**/test-results/
+**/playwright-report/
+**/playwright/.cache/
+**/logs/
+npm-debug.log*
+
+# ── Evalstone run reports (written by `evalstone run`) ──────────────────
+**/evalstone-report.json

evalstone-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog — evalstone (the library)
+
+All notable changes to `python/evalstone`. Semantic versioning; tags `lib-vX.Y.Z`.
+
+## 0.1.0 — 2026-10-13
+
+The first usable release: the hero path from `evalstone.yaml` to a gated run.
+
+- **Core**: `Sample` / `Dataset` (JSONL, content-hashed versions, deterministic
+  filter / sample / split), `Output`, `Score` (an error is never a pass), the
+  `Check` protocol, `@check`, the registry.
+- **Deterministic checks**: `exact`, `contains`, `regex`, `json_schema`
+  (JSON Schema or pydantic), `numeric_tolerance`, `length`, `python`.
+- **Targets**: `callable`, `http`, `recorded`, `prompt`.
+- **Suite / Run / Gate**: per-check and per-tag summaries, dataset hash + git SHA
+  provenance, baseline regression gate, error-rate gate (default 0), JSON
+  report, `compare`.
+- **CLI**: `init`, `run`, `gate`, `compare`, `show`, `list`.
+- **Providers**: OpenAI-compatible (OpenAI, OpenRouter, Ollama, vLLM),
+  Anthropic (official SDK, `evalstone[anthropic]`), Gemini; pricing table with
+  overrides; unknown models reported as unpriced.
+- **LLM-as-judge**: rubric → small scale → JSON verdict, reference excluded
+  unless asked, judge version hash, content-keyed cache.
+- **RAG** (faithfulness, context relevance, answer relevance), **safety**
+  (refusal, no_pii, forbidden), **pairwise** comparison (both orders),
+  **trajectory** (tool_called, tool_order, max_steps, no_repeated_calls, finished).
+- **Sample**: `samples/rag-bot` — a no-LLM retrieval bot with a gated suite.
+- **MCP server** (`evalstone mcp`, extra `evalstone[mcp]`): `list_suites`,
+  `run_suite`, `judge_output`, `record_sample`, `compare_runs`, `get_run` over
+  stdio; calls run one at a time, stray stdout goes to stderr, one provider
+  registry and judge cache per session, report paths relative to the config.
+- **pytest plugin** (entry point `pytest11`): `@suite("name")`, fixtures
+  `evalstone_run` / `evalstone_gate` / `evalstone_config`, options
+  `--evalstone-config` and `--evalstone-baseline` (a report or a directory of
+  them); one report per suite (`evalstone-report.<suite>.json`); a suite without
+  a gate fails the gated forms; the package imports lazily so the plugin costs
+  nothing in unrelated test sessions.
+- **GitHub Action** (`action/`): run a suite on a pull request, job summary,
+  in-place PR comment (`evalstone show --markdown`), fail on the gate; inputs
+  bound through the environment; `report` output is an absolute path.
+- **Human labels**: `evalstone label <report>` grades outputs in the terminal
+  (pass/fail or a 1..N scale, resumable, keyed by sample id + output hash); the
+  `human` check scores from the labels file and errors on unlabelled outputs.
+- **Reports**: `Run.markdown()`, `Run.failure_lines()`, results carry the
+  sample's input and expected value.
+- **Loading**: project modules are reused across runs in one process unless a
+  file changed or the registry was cleared, so test patches reach suites.

evalstone-0.1.0/LICENSE

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

evalstone-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: evalstone
+Version: 0.1.0
+Summary: The plug-and-play evals layer for LLM-based projects: datasets, checks, suites, runs and gates.
+Project-URL: Homepage, https://evalstone.com
+Project-URL: Documentation, https://evalstone.com/docs
+Project-URL: Repository, https://github.com/marceloribeiro/evalstone
+Author: Marcelo Ribeiro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,evals,evaluation,llm,rag,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: jsonschema<5,>=4.26
+Requires-Dist: pydantic<3,>=2.14
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: rich<16,>=15.0
+Requires-Dist: typer<1,>=0.27
+Provides-Extra: anthropic
+Requires-Dist: anthropic<2,>=1.13; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic<2,>=1.13; extra == 'dev'
+Requires-Dist: mcp<3,>=2.3; extra == 'dev'
+Requires-Dist: pytest>=9.1; extra == 'dev'
+Requires-Dist: respx>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# evalstone
+
+The plug-and-play evals layer for LLM-based projects, as a Python library.
+
+> **Status:** 0.1.0. Docs: [evalstone.com/docs/evalstone/library](https://evalstone.com/docs/evalstone/library).
+> Source and samples: [github.com/marceloribeiro/evalstone](https://github.com/marceloribeiro/evalstone).
+
+The library **computes**; it owns no database. A run lives in memory, prints a
+table and writes a JSON report. Persistence happens through the Evalstone
+center (PostgreSQL) when one is configured.
+
+## Develop
+
+```bash
+just install     # venv + editable install with dev extras
+just check       # ruff + pytest
+just console     # REPL with `es` loaded
+```
+
+## Quick start
+
+```bash
+pip install evalstone
+evalstone init my-evals                  # evalstone.yaml + a golden set + recorded outputs + a check
+cd my-evals
+evalstone run nightly                    # table + evalstone-report.json
+evalstone gate nightly                   # exit 1 when the gate fails (CI)
+```
+
+A fuller example — a small retrieval bot with a gated suite — lives in the
+repository under `samples/rag-bot` (`git clone` it, `pip install -e
+python/evalstone`, then `evalstone run nightly` inside the sample).
+
+Judges and prompt targets need a provider key in the environment
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, or any
+OpenAI-compatible base URL such as OpenRouter or Ollama via `providers:`).
+Without one, judge results are **errors, never passes**, and the gate fails.
+
+## Human labels
+
+```bash
+evalstone run nightly --report r.json
+evalstone label r.json --out evals/labels.jsonl      # p/f per output, or --scale 5
+```
+
+Labels are keyed by sample id **and** a hash of the output, so a changed answer
+never inherits an old grade; outputs whose target errored are not offered for
+grading. `--scale N` passes at N-1 (a 2-point scale at 2), as judges do. A
+`human` check (`{type: human, labels: evals/labels.jsonl}`, path relative to
+`evalstone.yaml`) scores from them; an unlabelled output is an error, never a
+pass. Labels are also the ground truth judges get calibrated against (center).
+
+## pytest
+
+```python
+from evalstone.pytest_plugin import suite
+
+
+@suite("nightly")  # runs the suite; a failing gate fails the test
+def test_support_bot(run):  # optional body sees the Run
+    assert run.summary.cost_usd < 1.0
+```
+
+Fixtures `evalstone_run` / `evalstone_gate` / `evalstone_config`; options
+`--evalstone-config`, `--evalstone-baseline` (a report, or a directory of them).
+Each suite writes `evalstone-report.<suite>.json` beside the config; paths are
+relative to the config's directory. A suite without a `gate:` fails the gated
+forms. Works on test methods too. The plugin registers itself when evalstone is
+installed, imports nothing of evalstone until a fixture runs, and pytest is not
+a runtime dependency of the library.
+
+## MCP server
+
+```bash
+pip install "evalstone[mcp]"
+claude mcp add evalstone -- evalstone mcp      # run from the project directory
+```
+
+Tools: `list_suites`, `run_suite`, `judge_output`, `record_sample`, `compare_runs`,
+`get_run`. The agent edits your prompt, runs the suite, reads the failures, and
+compares runs — the gate stays yours. Report paths are relative to the directory
+holding `evalstone.yaml` (pass `--config` to serve a project from elsewhere).
+
+## Concepts
+
+`Sample` → `Dataset` (content-hashed, so every run pins an exact version) ·
+`Check` → `Score` (0..1 + pass/fail + reason; an error is never a pass) ·
+`Suite` → `Run` → `Gate`. See the docs for the full vocabulary.

evalstone-0.1.0/README.md

@@ -0,0 +1,88 @@
+# evalstone
+
+The plug-and-play evals layer for LLM-based projects, as a Python library.
+
+> **Status:** 0.1.0. Docs: [evalstone.com/docs/evalstone/library](https://evalstone.com/docs/evalstone/library).
+> Source and samples: [github.com/marceloribeiro/evalstone](https://github.com/marceloribeiro/evalstone).
+
+The library **computes**; it owns no database. A run lives in memory, prints a
+table and writes a JSON report. Persistence happens through the Evalstone
+center (PostgreSQL) when one is configured.
+
+## Develop
+
+```bash
+just install     # venv + editable install with dev extras
+just check       # ruff + pytest
+just console     # REPL with `es` loaded
+```
+
+## Quick start
+
+```bash
+pip install evalstone
+evalstone init my-evals                  # evalstone.yaml + a golden set + recorded outputs + a check
+cd my-evals
+evalstone run nightly                    # table + evalstone-report.json
+evalstone gate nightly                   # exit 1 when the gate fails (CI)
+```
+
+A fuller example — a small retrieval bot with a gated suite — lives in the
+repository under `samples/rag-bot` (`git clone` it, `pip install -e
+python/evalstone`, then `evalstone run nightly` inside the sample).
+
+Judges and prompt targets need a provider key in the environment
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, or any
+OpenAI-compatible base URL such as OpenRouter or Ollama via `providers:`).
+Without one, judge results are **errors, never passes**, and the gate fails.
+
+## Human labels
+
+```bash
+evalstone run nightly --report r.json
+evalstone label r.json --out evals/labels.jsonl      # p/f per output, or --scale 5
+```
+
+Labels are keyed by sample id **and** a hash of the output, so a changed answer
+never inherits an old grade; outputs whose target errored are not offered for
+grading. `--scale N` passes at N-1 (a 2-point scale at 2), as judges do. A
+`human` check (`{type: human, labels: evals/labels.jsonl}`, path relative to
+`evalstone.yaml`) scores from them; an unlabelled output is an error, never a
+pass. Labels are also the ground truth judges get calibrated against (center).
+
+## pytest
+
+```python
+from evalstone.pytest_plugin import suite
+
+
+@suite("nightly")  # runs the suite; a failing gate fails the test
+def test_support_bot(run):  # optional body sees the Run
+    assert run.summary.cost_usd < 1.0
+```
+
+Fixtures `evalstone_run` / `evalstone_gate` / `evalstone_config`; options
+`--evalstone-config`, `--evalstone-baseline` (a report, or a directory of them).
+Each suite writes `evalstone-report.<suite>.json` beside the config; paths are
+relative to the config's directory. A suite without a `gate:` fails the gated
+forms. Works on test methods too. The plugin registers itself when evalstone is
+installed, imports nothing of evalstone until a fixture runs, and pytest is not
+a runtime dependency of the library.
+
+## MCP server
+
+```bash
+pip install "evalstone[mcp]"
+claude mcp add evalstone -- evalstone mcp      # run from the project directory
+```
+
+Tools: `list_suites`, `run_suite`, `judge_output`, `record_sample`, `compare_runs`,
+`get_run`. The agent edits your prompt, runs the suite, reads the failures, and
+compares runs — the gate stays yours. Report paths are relative to the directory
+holding `evalstone.yaml` (pass `--config` to serve a project from elsewhere).
+
+## Concepts
+
+`Sample` → `Dataset` (content-hashed, so every run pins an exact version) ·
+`Check` → `Score` (0..1 + pass/fail + reason; an error is never a pass) ·
+`Suite` → `Run` → `Gate`. See the docs for the full vocabulary.

evalstone-0.1.0/justfile

@@ -0,0 +1,37 @@
+# evalstone — the library. Builder-convention justfile (no database: the library owns none).
+set dotenv-load := true
+
+venv := "venv/bin"
+python := env_var_or_default("PYTHON", "python3.13")
+
+# Install the package in editable mode with dev extras into ./venv (PYTHON=python3.12 to override).
+install:
+    test -d venv || {{python}} -m venv venv
+    {{venv}}/pip install -q --upgrade pip
+    {{venv}}/pip install -q -e ".[dev]"
+
+# Run the test suite.
+test:
+    {{venv}}/pytest
+
+# Lint (ruff check) without changing files.
+lint:
+    {{venv}}/ruff check .
+    {{venv}}/ruff format --check .
+
+# Tests + linters — run before pushing (same as CI).
+check: lint test
+
+# Auto-fix lint problems and format the code.
+formatters-fix:
+    {{venv}}/ruff check --fix .
+    {{venv}}/ruff format .
+
+# Python REPL with evalstone imported.
+console:
+    {{venv}}/python -i -c "import evalstone as es; print('evalstone', es.__version__, '— `es` is loaded')"
+
+# Build sdist + wheel into dist/.
+build:
+    {{venv}}/pip install -q build
+    {{venv}}/python -m build

evalstone-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "evalstone"
+dynamic = ["version"]
+description = "The plug-and-play evals layer for LLM-based projects: datasets, checks, suites, runs and gates."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Marcelo Ribeiro" }]
+keywords = ["llm", "evals", "evaluation", "testing", "rag", "agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = [
+  "httpx>=0.28,<1",
+  "jsonschema>=4.26,<5",
+  "pydantic>=2.14,<3",
+  "pyyaml>=6.0,<7",
+  "rich>=15.0,<16",
+  "typer>=0.27,<1",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=1.13,<2"]
+mcp = ["mcp>=2.3,<3"]
+dev = [
+  "anthropic>=1.13,<2",
+  "mcp>=2.3,<3",
+  "pytest>=9.1",
+  "respx>=0.23",
+  "ruff>=0.17",
+]
+
+[project.scripts]
+evalstone = "evalstone.cli:main"
+
+[project.entry-points.pytest11]
+evalstone = "evalstone.pytest_plugin"
+
+[project.urls]
+Homepage = "https://evalstone.com"
+Documentation = "https://evalstone.com/docs"
+Repository = "https://github.com/marceloribeiro/evalstone"
+
+[tool.hatch.version]
+path = "src/evalstone/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/evalstone"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.format]
+quote-style = "double"

evalstone-0.1.0/src/evalstone/__init__.py

@@ -0,0 +1,131 @@
+"""Evalstone — the plug-and-play evals layer for LLM-based projects.
+
+The library computes; it owns no database. See https://evalstone.com/docs.
+"""
+
+import sys
+import types
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+__version__ = "0.1.0"
+
+# Exports resolve on first access (PEP 562) so that importing the package — which
+# the pytest plugin does in every pytest session on the interpreter — costs
+# nothing until a name is used.
+_EXPORTS: dict[str, str] = {
+    "check": "evalstone.checks",
+    "registry": "evalstone.checks",
+    "Dataset": "evalstone.dataset",
+    "Sample": "evalstone.dataset",
+    "Source": "evalstone.dataset",
+    "Gate": "evalstone.gate",
+    "GateFailed": "evalstone.gate",
+    "GateReport": "evalstone.gate",
+    "Output": "evalstone.output",
+    "Providers": "evalstone.providers",
+    "Comparison": "evalstone.run",
+    "Result": "evalstone.run",
+    "Run": "evalstone.run",
+    "RunSummary": "evalstone.run",
+    "compare": "evalstone.run",
+    "write_report": "evalstone.run",
+    "Check": "evalstone.score",
+    "CheckKind": "evalstone.score",
+    "Context": "evalstone.score",
+    "MemoryCache": "evalstone.score",
+    "Score": "evalstone.score",
+    "Suite": "evalstone.suite",
+    "CallableTarget": "evalstone.target",
+    "HttpTarget": "evalstone.target",
+    "PromptTarget": "evalstone.target",
+    "RecordedTarget": "evalstone.target",
+    "Target": "evalstone.target",
+    "target": "evalstone.target",
+}
+
+if TYPE_CHECKING:
+    from evalstone import checks
+    from evalstone.checks import check, registry
+    from evalstone.dataset import Dataset, Sample, Source
+    from evalstone.gate import Gate, GateFailed, GateReport
+    from evalstone.output import Output
+    from evalstone.providers import Providers
+    from evalstone.run import Comparison, Result, Run, RunSummary, compare, write_report
+    from evalstone.score import Check, CheckKind, Context, MemoryCache, Score
+    from evalstone.suite import Suite
+    from evalstone.target import (
+        CallableTarget,
+        HttpTarget,
+        PromptTarget,
+        RecordedTarget,
+        Target,
+        target,
+    )
+
+
+class _Package(types.ModuleType):
+    """``evalstone.target`` is the factory function, as it always was, even though a
+    submodule of the same name exists: importing that submodule makes the import
+    system bind it onto the package, which the setter below ignores."""
+
+    @property
+    def target(self) -> Any:
+        return import_module("evalstone.target").target
+
+    @target.setter
+    def target(self, value: Any) -> None:
+        pass
+
+
+sys.modules[__name__].__class__ = _Package
+
+
+def __getattr__(name: str) -> Any:
+    if name == "checks":
+        return import_module("evalstone.checks")
+    try:
+        module = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module 'evalstone' has no attribute {name!r}") from None
+    value = getattr(import_module(module), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(__all__) | {n for n in globals() if n.startswith("__")})
+
+
+__all__ = [
+    "CallableTarget",
+    "Check",
+    "CheckKind",
+    "Comparison",
+    "Context",
+    "Dataset",
+    "Gate",
+    "GateFailed",
+    "GateReport",
+    "HttpTarget",
+    "MemoryCache",
+    "Output",
+    "PromptTarget",
+    "Providers",
+    "RecordedTarget",
+    "Result",
+    "Run",
+    "RunSummary",
+    "Sample",
+    "Score",
+    "Source",
+    "Suite",
+    "Target",
+    "__version__",
+    "check",
+    "checks",
+    "compare",
+    "registry",
+    "target",
+    "write_report",
+]

evalstone-0.1.0/src/evalstone/__main__.py

@@ -0,0 +1,3 @@
+from evalstone.cli import main
+
+main()

evalstone-0.1.0/src/evalstone/_git.py

@@ -0,0 +1,22 @@
+"""Best-effort git facts for run provenance. Never raises."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def head_sha(cwd: str | Path | None = None) -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    sha = out.stdout.strip()
+    return sha if out.returncode == 0 and sha else None

evalstone-0.1.0/src/evalstone/_json.py

@@ -0,0 +1,59 @@
+"""Canonical JSON helpers: one stable serialisation so content hashes are reproducible.
+
+Only JSON-native values plus a few explicitly handled types (sets, tuples,
+bytes, dates, enums, pydantic models, dataclasses) are accepted. Anything else
+raises ``TypeError`` instead of being stringified — ``str(obj)`` would bake a
+memory address or a hash-randomised set order into a content hash.
+"""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import datetime as dt
+import enum
+import hashlib
+import json
+from typing import Any
+
+
+def _encode(value: Any) -> Any:
+    """Convert the supported non-JSON types to a deterministic JSON-native form."""
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    if isinstance(value, list):
+        return [_encode(v) for v in value]
+    if isinstance(value, dict):
+        if any(not isinstance(k, str) for k in value):
+            raise TypeError("dict keys must be strings to hash")
+        return {k: _encode(v) for k, v in value.items()}
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, set | frozenset):
+        return sorted((_encode(v) for v in value), key=lambda v: json.dumps(v, sort_keys=True))
+    if isinstance(value, tuple):
+        return [_encode(v) for v in value]
+    if isinstance(value, bytes | bytearray):
+        return {"__bytes__": base64.b64encode(bytes(value)).decode("ascii")}
+    if isinstance(value, dt.datetime | dt.date | dt.time):
+        return value.isoformat()
+    if hasattr(value, "model_dump") and callable(value.model_dump):  # pydantic
+        return value.model_dump(mode="json")
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return dataclasses.asdict(value)
+    raise TypeError(f"not JSON-serialisable for hashing/text: {type(value).__name__}")
+
+
+def dumps(value: Any, **kwargs: Any) -> str:
+    """``json.dumps`` with the explicit encoder above (never ``default=str``)."""
+    return json.dumps(_encode(value), ensure_ascii=False, **kwargs)
+
+
+def canonical(value: Any) -> str:
+    """Serialise ``value`` deterministically (sorted keys, no whitespace, UTF-8 kept)."""
+    return dumps(_encode(value), sort_keys=True, separators=(",", ":"))
+
+
+def sha256(value: Any) -> str:
+    """sha256 hex digest of the canonical JSON form of ``value``."""
+    return hashlib.sha256(canonical(value).encode("utf-8")).hexdigest()