ruthless-efficiency 0.2.0__tar.gz

ruthless_efficiency-0.2.0/.gitattributes

@@ -0,0 +1,10 @@
+# Normalize line endings to LF in the repository for cross-platform consistency
+# (CI runs on Linux; contributors may be on Windows/macOS).
+* text=auto eol=lf
+
+# Binary assets — never normalize.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary

ruthless_efficiency-0.2.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @karsten-s-nielsen

ruthless_efficiency-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug Report
+about: Report a bug in ruthless-efficiency
+title: "[Bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+```python
+# Minimal code to reproduce
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- ruthless-efficiency version:
+- Python version:
+- numpy version:
+- pydantic version:
+- OS:
+
+**Additional context**
+Any other context (stack trace, config sample, etc.)

ruthless_efficiency-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature Request
+about: Suggest a feature for ruthless-efficiency
+title: "[Feature] "
+labels: enhancement
+---
+
+**Is this related to a problem?**
+A clear description of the problem. E.g., "I'm frustrated when..."
+
+**Proposed solution**
+Describe the solution you'd like.
+
+**Alternatives considered**
+Any alternative solutions or features you've considered.
+
+**Additional context**
+Any other context (links to papers, related strategies/backends, etc.)

ruthless_efficiency-0.2.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

ruthless_efficiency-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+Brief description of what this PR does.
+
+## Changes
+
+- 
+
+## Testing
+
+- [ ] Tests pass (`pytest -v`)
+- [ ] Lint clean (`ruff check ruthless tests`)
+- [ ] Format clean (`ruff format --check ruthless tests`)
+- [ ] Types clean (`pyright`)
+- [ ] Import contracts kept (`lint-imports`)
+
+## Related issues
+
+Closes #

ruthless_efficiency-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+      - run: uv python install 3.10
+      - run: uv venv --python 3.10
+      - run: uv pip install -e ".[dev,backends,evolve,optuna]"
+      - run: uv run ruff check ruthless tests
+      - run: uv run ruff format --check ruthless tests
+      - run: uv run pyright
+      - run: uv run lint-imports
+      - run: uv run pytest -v
+
+  core-lean:
+    # Proves the default install stays dependency-light: core imports + the core test subset
+    # must pass WITHOUT the [backends]/[evolve]/[optuna] heavy deps (huggingface_hub/docker/openevolve/optuna).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+      - run: uv python install 3.10
+      - run: uv venv --python 3.10
+      - run: uv pip install -e ".[dev]"
+      - run: uv run python -c "import ruthless; from ruthless.strategies.random_.strategy import RandomSearchStrategy; print(ruthless.__version__)"
+      - run: uv run pytest -v --ignore=tests/backends --ignore=tests/strategies/evolve --ignore=tests/e2e/test_evolve_orchestration_gate.py --ignore=tests/strategies/optuna_ --ignore=tests/e2e/test_optuna_resume_gate.py

ruthless_efficiency-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          print-hash: true

ruthless_efficiency-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+.pytest_cache/
+dist/
+*.egg-info/
+.import_linter_cache/
+
+# Claude Code
+.claude/

ruthless_efficiency-0.2.0/.importlinter

@@ -0,0 +1,44 @@
+[importlinter]
+root_packages =
+    ruthless
+
+[importlinter:contract:core-isolation]
+name = core must not import strategies or backends
+type = forbidden
+source_modules =
+    ruthless._io
+    ruthless._logging
+    ruthless.errors
+    ruthless.result
+    ruthless.objective
+    ruthless.backend
+    ruthless.strategy
+    ruthless.guards
+    ruthless.parallel
+    ruthless.config
+    ruthless.config.common
+    ruthless.config.space
+    ruthless.config.strategies
+    ruthless.report
+    ruthless.remote
+    ruthless.testing
+    ruthless.wire
+forbidden_modules =
+    ruthless.strategies
+    ruthless.backends
+
+[importlinter:contract:strategy-isolation]
+name = strategies must not import backends or each other
+type = forbidden
+source_modules =
+    ruthless.strategies
+forbidden_modules =
+    ruthless.backends
+
+[importlinter:contract:backends-isolation]
+name = backends must not import strategies
+type = forbidden
+source_modules =
+    ruthless.backends
+forbidden_modules =
+    ruthless.strategies

ruthless_efficiency-0.2.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) (with the usual `0.x` caveat: the public
+API may change between minor versions until `1.0`).
+
+## [0.2.0] - 2026-05-28
+
+First published release. Ships the Phase 2 `[optuna]` extra alongside the Phase 1A/1B core, and folds
+in the 2026-05-28 audit cleanup (curated public API, value-object immutability, security hardening).
+
+### Added
+- `[optuna]` extra: `OptunaStrategy` — resumable Bayesian/sampler calibration on a SQLite study
+  (single-process resume; warm-start; C3 resume contract).
+- `CachedObjective` core Protocol (one-time `prepare()` invariant + per-trial `evaluate_patch`) and
+  `ruthless.testing.assert_cache_equivalence`, proving the fast path equals the full recompute.
+- Curated top-level public API: import the supported surface from `ruthless` directly
+  (`from ruthless import Candidate, RandomConfig, RandomSearchStrategy, InProcessBackend, ...`), with
+  an explicit `__all__`. Per-strategy namespaces re-export their strategy
+  (`ruthless.strategies.random_`, `…optuna_`, `…evolve_`).
+- `ruthless.wire` — single source of truth for the cross-wire failure/score contract
+  (`combined_score` / `error` / `_error_text`), replacing magic strings duplicated across backends.
+- `docs/adr/ADR-001-ast-sandbox-security-model.md` — the security model behind the evolve AST
+  allowlist (previously a dangling reference).
+- `benchmarks/` — pytest-benchmark performance baselines for the random-search loop and
+  `assert_cache_equivalence` (not part of the default test run).
+
+### Changed
+- `ruthless.config` is now a package (`space` / `common` / `strategies` submodules) instead of a
+  single module. All public names still import from `ruthless.config` — no import sites change.
+- `Candidate.params` is now a read-only mapping (frozen + defensively copied at construction) and
+  `Choice.choices` is a tuple, enforcing the value-object immutability the dedup-key invariant relies
+  on. Consumers that need a mutable copy use `dict(candidate.params)`.
+
+### Security
+- SSH backend: all `ssh`/`scp` calls now use `BatchMode=yes` and `StrictHostKeyChecking=accept-new`;
+  `HF_TOKEN` is transferred to the remote node via a 0600 file (read once, then unlinked) instead of
+  an inline command-line env prefix, keeping it out of the remote `ps`/shell history.
+- `BackendConfig` validates `device` / `ssh_remote_dir` / `ssh_python_path` against a shell-safe
+  allowlist (blocks injection when a config is sourced from templated input).
+- CI workflow actions are pinned to commit SHAs (supply-chain hardening), matching the publish
+  workflow.
+
+## [0.1.0]
+
+### Added
+- Hexagonal core: the `Objective`, `SearchStrategy`, and `ComputeBackend` ports; the `Candidate`,
+  `Metrics`, `Evaluation`, and `Result` value types; the discriminated-union config surface; JSON +
+  Markdown reporting; the unified error taxonomy (`TransientEvaluationError` /
+  `FatalEvaluationError`); and `InProcessBackend`.
+- `RandomSearchStrategy` — the built-in zero-dependency baseline and the driver of the
+  determinism/convergence gate (Phase 1A).
+- `[backends]` extra: `BackendPool` (priority-ordered dispatch + bounded transient-retry) over
+  `local_cuda` / `remote_ssh` / `hf_jobs` / `docker`, with the `RemoteObjective` / `RemoteRef`
+  remote-resolution contract (Phase 1B).
+- `[evolve]` extra: `EvolveStrategy` — a thin orchestration adapter over OpenEvolve — plus the AST
+  allowlist validator for Level-2 code evolution (Phase 1B).

ruthless_efficiency-0.2.0/CLAUDE.md

@@ -0,0 +1,123 @@
+# ruthless-efficiency
+
+A general optimisation/search substrate: a pure hexagonal core + pluggable search strategies +
+pluggable compute backends. Ships at `0.2.0` (`0.x` — API unstable). **Phase 1A** delivered the core
+ports + built-in `RandomSearchStrategy` (determinism gate). **Phase 1B (library side)** adds the
+optional `[backends]` extra (`BackendPool` + `local_cuda`/`remote_ssh`/`hf_jobs`/`docker`, with the
+per-candidate timeout + transient-retry contract) and the `[evolve]` extra (`EvolveStrategy`, a thin
+adapter over OpenEvolve, + the AST sandbox). **Phase 2 (library side)** adds the `[optuna]` extra
+(`OptunaStrategy` — resumable Bayesian/sampler calibration; `CachedObjective` invariant-prep /
+per-trial-patch port + `ruthless.testing.assert_cache_equivalence`). The consumer migrations (lakehouse
+evolve, and **silly-kicks adopting `ruthless[optuna]`** for its own calibrations) run in those repos,
+not here.
+
+## Architecture
+
+- **Hexagonal.** `ruthless/` is the pure core: it defines the **ports** (`Objective`,
+  `SearchStrategy`, `ComputeBackend` — structural `Protocol`s) and **value types** (`Candidate`,
+  `Metrics = dict[str, float]`, `Evaluation`, `Result`). The core depends only on `pydantic` +
+  `numpy` (+ `pyyaml`).
+- **One-way dependency direction.** Strategies (`ruthless/strategies/`) and backends
+  (`ruthless/backends/`) depend on the core, never the reverse; strategies do not import each other or
+  the backends package, and backends do not import strategies. Enforced by import-linter
+  (`.importlinter`, **3 contracts**) — `lint-imports` must stay green. (`EvolveStrategy` receives a
+  backend via `run(objective, *, backend)`; its OpenEvolve worker script imports `create_backend` at
+  runtime in the worker subprocess — not a static strategy→backends import.)
+- **Each strategy owns its loop.** The core imposes no template-method driver. A strategy drives the
+  search and returns a `Result`; `report.py` renders it (JSON + Markdown). Persistence/resume is
+  strategy-internal.
+- **Backends are the inter-candidate dispatch path.** One evaluation → one compute resource, on the
+  single port `evaluate(candidate, objective, *, timeout) -> Metrics`. `InProcessBackend` (core) runs
+  `objective.evaluate(candidate)` for pure/CPU objectives. The `[backends]` compute backends require a
+  **`RemoteObjective`** (an objective that opts into remote execution via a `RemoteRef` = install spec
+  + `module:callable` entrypoint, replacing the old `shared.wheel`/`target` convention); they resolve
+  and run the entrypoint (`local_cuda` in-process; `remote_ssh`/`hf_jobs` on a node). The
+  cross-process backends (`remote_ssh`/`hf_jobs`) enforce the per-candidate `timeout`; the in-process
+  ones (`InProcessBackend`, `local_cuda`) accept it for port compatibility but cannot cancel
+  in-process work, so they document-and-ignore it. `BackendPool` is a priority-ordered pool with a
+  bounded transient-retry contract.
+- **Unified error model (1B).** Backends never record a sentinel score: they **raise**
+  `TransientEvaluationError` (transport/infra — retried by the pool) or `FatalEvaluationError`
+  (unparseable output / missing `remote_ref` / a node-side objective-crash marker). For evolve, the
+  `EvolveEvaluator` is the **single** place that maps any failure to the OpenEvolve worst-score
+  sentinel (objective vs. infra distinguished in artifacts), because OpenEvolve needs a score per
+  candidate.
+
+## Key conventions
+
+- **Scored-metric finiteness only.** `classify_metric()` raises `FatalEvaluationError` if the
+  *optimisation-target* metric is inf/NaN. Diagnostic/auxiliary metrics are allowed to be non-finite
+  — never pass them to `classify_metric()`.
+- **Fatal errors vs. penalties are distinct.** Fatal evaluation failures (`ruthless.errors`) are
+  surfaced and **never** recorded as a score. Degenerate-but-valid candidates get a recorded penalty
+  (`ruthless.guards.penalty_metrics`) — a finite, deliberately-bad score, not an error.
+- **`Candidate` is hashable** (frozen, order-independent `__eq__`/`__hash__` over its params) so it
+  can serve as a cache/dedup key. Do not mutate `params` after construction.
+- **`Result` is treat-as-immutable once returned** by `SearchStrategy.run`.
+- **Config is a discriminated-union surface.** `RuthlessConfig` carries a discriminated *strategy*
+  union and a discriminated *param-space* union (`FloatRange` / `IntRange` / `Choice`, with a `log`
+  flag on floats). Only `random` is registered in Phase 1A; evolve/optuna extend the union later
+  without a breaking change.
+- **Library never configures root logging.** Use `ruthless._logging.get_logger(name)` →
+  `logging.getLogger("ruthless.<name>")`. No handlers are attached; consumers own that.
+- **The CLI objective loader is trusted-config-only.** `resolve_objective("pkg.mod:attr")` uses
+  `importlib` + `getattr` (never `eval`) and isinstance-checks against `Objective` (a name-only
+  guard). Programmatic construction is the primary API.
+
+## Local quality gate (mirrors CI exactly)
+
+Run all five before declaring work done (Shift Left — catch it locally, not in CI):
+
+```bash
+uv run ruff check ruthless tests
+uv run ruff format --check ruthless tests
+uv run pyright
+uv run lint-imports
+uv run pytest -v
+```
+
+`pyright` runs on **both** `ruthless` and `tests` (see `[tool.pyright] include`).
+
+## Workflow conventions
+
+- **TDD** — write the failing test first, then implement (red → green per change).
+- **`/final-review`** is the mandatory pre-commit quality gate for every work cycle (it also
+  generates/updates the C4 diagram at `docs/c4/architecture.html`).
+- **No commit without explicit user approval.**
+- **No git worktrees** — project convention; work on a feature branch in this repo.
+
+## Tech stack
+
+Python ≥3.10 (CI on 3.10), pydantic v2, numpy (`<3`, pinned for RNG-stream stability of the
+determinism gate), pyyaml. Dev: pytest + hypothesis, ruff, pyright, import-linter, hatchling.
+
+## Scope map
+
+- **Phase 1A (done):** core ports + value types + config + reporting + observability +
+  `RandomSearchStrategy` + the determinism/convergence gate.
+- **Plan 1B — library side (done):** `[backends]` (`BackendPool` + `local_cuda`/`remote_ssh`/`hf_jobs`/
+  `docker`, timeout + transient-retry contract, `RemoteObjective`/`RemoteRef`) and `[evolve]`
+  (`EvolveStrategy` over OpenEvolve + the AST sandbox). **Part C (lakehouse consumer migration)** is
+  pending and runs in the lakehouse repo (behind its hard-gate).
+- **Phase 2 — library side (done):** `[optuna]` (`OptunaStrategy` — resumable SQLite study, warm-start,
+  C3 resume contract; `CachedObjective` + `ruthless.testing.assert_cache_equivalence`). Group-scoring
+  was **deferred** (consumer runs CV in its own `score_fn`). **Consumer adoption pending:** silly-kicks
+  installs `ruthless[optuna]` and owns its parameter objectives (the first real consumer); lakehouse
+  evolve + TC3 migrations later.
+
+## Key Phase-2 conventions
+
+- **`CachedObjective`** (core Protocol, no optuna dep): full `evaluate` + `prepare()` (invariant, once)
+  + `evaluate_patch(invariant, candidate)` + `patch_params`. `OptunaStrategy` uses the fast path and
+  rejects tuning any param not in `patch_params` (H1/M5). `assert_cache_equivalence` proves fast==full
+  and ENFORCES that candidates vary every patch_param.
+- **OptunaStrategy resume (C3):** no lost/dup trials + monotone growth + converge — NOT trajectory
+  identity (Optuna doesn't persist sampler RNG). `best`/`history` are reconstructed from `study.trials`
+  so they span the whole store on resume. SQLite store = single-process only.
+
+## Reference docs
+
+- Spec: `docs/superpowers/specs/2026-05-28-optimization-engine-carveout-design.md`
+- Phase 1A plan: `docs/superpowers/plans/2026-05-28-ruthless-efficiency-phase1a.md`
+- Phase 1B plan (rev 3): `docs/superpowers/plans/2026-05-28-ruthless-efficiency-phase1b.md`
+- Phase 2 plan (rev 3): `docs/superpowers/plans/2026-05-28-ruthless-efficiency-phase2-library.md`

ruthless_efficiency-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

ruthless_efficiency-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to ruthless-efficiency
+
+## Development Setup
+
+```bash
+git clone https://github.com/karsten-s-nielsen/ruthless-efficiency.git
+cd ruthless-efficiency
+uv venv --python 3.10
+uv pip install -e ".[dev]"                          # core-only dev install
+# For the FULL test suite (backends/evolve/optuna tests + e2e gates), install the extras too:
+uv pip install -e ".[dev,backends,evolve,optuna]"
+```
+
+The core-only install (`.[dev]`) runs the core test subset; the backend/strategy tests under
+`tests/backends/`, `tests/strategies/evolve/`, and `tests/strategies/optuna_/` (and their e2e gates)
+require the extras. CI runs both: a full `test` job with all extras and a `core-lean` job that proves
+the default install stays dependency-light.
+
+## Running Tests
+
+```bash
+# Full suite
+uv run pytest -v
+
+# A single module
+uv run pytest tests/test_random_strategy.py -v
+
+# Performance baselines (not part of the default run — see benchmarks/)
+uv run pytest benchmarks/ --benchmark-only
+```
+
+## Code Quality
+
+The full local gate mirrors CI exactly:
+
+```bash
+uv run ruff check ruthless tests
+uv run ruff format --check ruthless tests
+uv run pyright
+uv run lint-imports
+uv run pytest -v
+```
+
+All five must pass before opening a PR (Shift Left — catch it locally, not in CI).
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Write tests first (TDD preferred — red → green per change)
+3. Ensure the full gate above is green
+4. Keep commits focused — one logical change per commit
+5. Include a clear description of what and why
+
+## Architecture Guidelines
+
+- **Hexagonal / pure core.** `ruthless/` defines the ports (`Objective`, `SearchStrategy`,
+  `ComputeBackend`) and value types (`Candidate`, `Metrics`, `Result`) and depends only on
+  `pydantic` + `numpy` (+ `pyyaml`).
+- **Dependency direction is one-way.** Strategies and backends depend on the core, never the reverse.
+  This is enforced by import-linter (`.importlinter`) — `lint-imports` must stay green.
+- **Each strategy owns its loop.** The core imposes no template-method driver; a strategy drives the
+  search and returns a `Result` that `report.py` renders.
+- **Error taxonomy vs. penalties.** Fatal evaluation failures (`ruthless.errors`) are surfaced and
+  never recorded as a score; degenerate-but-valid candidates get a recorded penalty
+  (`ruthless.guards`). Only the *scored* metric is checked for finiteness. The cross-wire
+  failure-marker vocabulary (`combined_score`/`error`/`_error_text`) lives in `ruthless.wire`.
+- **Remote execution (`[backends]`).** Compute backends require a `RemoteObjective` exposing a
+  `RemoteRef` (install spec + `module:callable` entrypoint); `BackendPool` adds priority-ordered
+  dispatch with a bounded transient-retry contract. Backends *raise* `TransientEvaluationError`
+  (retried) or `FatalEvaluationError` (surfaced) — they never record a sentinel.
+- **Cached objectives (`[optuna]`).** `CachedObjective` (a core Protocol) declares a one-time
+  `prepare()` invariant + a per-trial `evaluate_patch`; `ruthless.testing.assert_cache_equivalence`
+  proves the fast path equals the full recompute. `OptunaStrategy` uses the fast path.
+- New public functions and classes need docstrings explaining what they do and how to use them.
+
+For the system-level view, download [`docs/c4/architecture.html`](docs/c4/architecture.html) and open
+it in a browser (C4 System Context / Container / Component diagrams). The conventions above are
+detailed in [`CLAUDE.md`](CLAUDE.md); the design rationale is in the
+[spec](docs/superpowers/specs/2026-05-28-optimization-engine-carveout-design.md).
+
+## Versioning
+
+The project is `0.x` — the ports are still being validated against real consumers. Breaking changes
+to the public ports (`Objective`, `SearchStrategy`, `ComputeBackend`) and value types may occur before
+`1.0`. Every release — and any breaking change — is recorded in [CHANGELOG.md](CHANGELOG.md).

ruthless_efficiency-0.2.0/LICENSE

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

ruthless_efficiency-0.2.0/NOTICE

@@ -0,0 +1,93 @@
+ruthless-efficiency
+Copyright (c) 2026 Karsten S. Nielsen
+
+This product is original work, released under the MIT License (see LICENSE).
+It is not a fork. The name and tagline are a homage to Monty Python (see
+"Assets and Cultural Attribution" below).
+
+
+Third-Party Libraries (runtime)
+-------------------------------
+
+Installed with the default distribution. Each retains its own upstream license;
+the SPDX expressions below were verified against the installed package metadata.
+
+pydantic --- data validation / settings (MIT License).
+  See: https://github.com/pydantic/pydantic
+
+numpy --- numerical arrays and the seeded RNG used by RandomSearchStrategy
+  (BSD-3-Clause License). Copyright (c) 2005-2024, NumPy Developers.
+  Pinned `>=1.24,<3` so the random-search RNG stream stays stable for the
+  determinism gate. See: https://github.com/numpy/numpy
+
+PyYAML --- YAML config parsing, via `yaml.safe_load` only (MIT License).
+  See: https://github.com/yaml/pyyaml
+
+
+Development and Build Tooling
+-----------------------------
+
+Used to test, lint, type-check, and build the project; NOT redistributed in the
+runtime wheel.
+
+pytest (MIT) --- test runner.
+hypothesis (MPL-2.0) --- property-based testing.
+ruff (MIT) --- linter and formatter.
+pyright (MIT) --- static type checker.
+import-linter (BSD-2-Clause) --- enforces the hexagonal dependency contracts
+  declared in `.importlinter`.
+hatchling (MIT) --- PEP 517 build backend.
+
+
+Optional Extras (not installed by default)
+------------------------------------------
+
+Declared in pyproject.toml under [project.optional-dependencies] and pulled in
+only when the matching extra is requested. Each retains its upstream license;
+none is bundled in the default distribution. These are integration points for
+later phases and are not consumed by any Phase 1A public API.
+
+optuna (MIT) --- `[optuna]`, Phase 2 (OptunaStrategy).
+openevolve --- `[evolve]`, Plan 1B (the evolve strategy is our orchestration
+  over OpenEvolve's loop).
+paramiko, huggingface_hub, docker --- `[backends]`, Plan 1B (SSH / Hugging Face
+  Jobs / Docker compute backends).
+
+
+Mathematical / Methodological References
+----------------------------------------
+
+The built-in random-search strategy (ruthless/strategies/random_/) implements
+the baseline described in: Bergstra, J., & Bengio, Y. (2012). "Random Search
+for Hyper-Parameter Optimization." Journal of Machine Learning Research, 13,
+281-305.
+
+The log-uniform sampling option (the `log` flag on FloatRange in
+ruthless/config.py) follows the convention popularised by Optuna's
+`suggest_float(log=True)`: Akiba, T., Sano, S., Yanase, T., Ohta, T., &
+Koyama, M. (2019). "Optuna: A Next-generation Hyperparameter Optimization
+Framework." Proc. KDD '19. (Optuna itself is an optional Phase 2 extra, not a
+Phase 1A dependency.)
+
+The ports-and-adapters ("hexagonal") structure of the core follows: Cockburn,
+A. (2005). "Hexagonal Architecture" (alistair.cockburn.us/hexagonal-architecture).
+The one-way core/strategy/backend dependency direction is enforced in CI by
+import-linter.
+
+
+Documentation Tooling
+---------------------
+
+The C4 architecture diagram (docs/c4/architecture.html) is authored in
+Structurizr DSL (docs/c4/architecture.dsl) and rendered locally via Structurizr
+and PlantUML. These tools are used only to produce the documentation artifact
+and are not part of the project's dependencies.
+
+
+Assets and Cultural Attribution
+-------------------------------
+
+The hero image (assets/ruthless-efficiency.jpg) and the project name/tagline
+("Our chief weapons are Ruthless Efficiency!") are an affectionate homage to
+Monty Python's "The Spanish Inquisition" sketch (Monty Python's Flying Circus,
+1970). No affiliation with or endorsement by the rights holders is implied.