goldilocks-core 0.1.0__tar.gz

goldilocks_core-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, UKRI Science and Technology Facilities Council
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

goldilocks_core-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: goldilocks-core
+Version: 0.1.0
+Summary: Materials machine learning tools for recommending DFT calculation inputs.
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ase>=3.28
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: pandas>=2.0
+Requires-Dist: pymatgen>=2026.3.23
+Requires-Dist: requests>=2.32
+Requires-Dist: goldilocks-ml==0.2.3
+Requires-Dist: pydantic>=2.12
+Provides-Extra: http
+Requires-Dist: fastapi; extra == "http"
+Requires-Dist: uvicorn; extra == "http"
+Provides-Extra: mcp
+Requires-Dist: mcp; extra == "mcp"
+Dynamic: license-file
+
+# goldilocks-core
+
+Goldilocks recommends settings for density functional theory (DFT) calculations
+and generates Quantum ESPRESSO input files (SCF, DOS, relaxation, and
+variable-cell relaxation) from a crystal structure.
+
+## Installation
+
+Not published to PyPI yet -- clone the repository. Install
+[uv](https://docs.astral.sh/uv/getting-started/installation/) first:
+
+```bash
+git clone https://github.com/junwen94/goldilocks-core.git
+cd goldilocks-core
+uv sync
+```
+
+## Try it
+
+### Start the Workbench
+
+With Node.js 24 or newer installed, run:
+
+```bash
+uv sync --extra http
+npm --prefix web ci
+uv run goldilocks assets install workbench
+uv run --extra http poe workbench
+```
+
+The asset step installs the models and pseudopotential tables. Open
+**http://127.0.0.1:5173**, upload a CIF or POSCAR, review the recommended
+settings, and download the generated inputs.
+
+For a built frontend instead, stop the development servers and run:
+
+```bash
+uv run --extra http poe stage
+```
+
+Then open **http://127.0.0.1:8000**. See the [Workbench guide](web/README.md)
+for Docker and development checks.
+
+#### With mMACE (ML-backed magnetism features)
+
+Without any extra setup, magnetism classification (`is_magnetic`) and
+magnetic-ordering ranking run at a heuristic/LLM tier. To get the real ML
+tier, install `mace`/`e3nn`/`sphericart` and a checkpoint file once, manually
+-- none of this can ever be a `pip`/`uv` extra (the `mace` fork it needs has
+no PyPI release):
+
+```bash
+uv pip install ase==3.28.0 e3nn==0.4.4 sphericart==1.0.9 sphericart-torch==1.0.9
+uv pip install "mace-torch @ git+https://github.com/CheukHinHoJerry/mace.git@19cdf6692c48e068a24e06cfe1ffc670e8aea3dd"
+mkdir -p ~/.local/share/goldilocks/mmace
+curl -L -o ~/.local/share/goldilocks/mmace/mace_matpes_pbe_baseline_run-3.model \
+  https://data-collections.psdi.ac.uk/api/records/1g8rw-q8128/files/mace_matpes_pbe_baseline_run-3.model/content
+export GOLDILOCKS_MACE_BACKBONE=~/.local/share/goldilocks/mmace/mace_matpes_pbe_baseline_run-3.model
+```
+
+Then start the Workbench as above **in the same shell** (the backend only
+picks up `GOLDILOCKS_MACE_BACKBONE` if it's set before launch). Load a
+magnetic structure (e.g.
+`src/goldilocks_core/examples/structures/Fe_bcc.cif`) and check the
+**Analysis** column's "is magnetic" field: its caption switches to
+**"Goldilocks-ML prediction"** once the `ml` tier is live.
+
+Two gotchas worth knowing up front: `uv sync` silently removes the two
+manually-installed packages again (they're not in `uv.lock`) -- re-run the
+`uv pip install` lines above after any `uv sync`; and the Workbench's own
+"Run mMACE" ranking button is currently broken
+([stfc/goldilocks-ml#95](https://github.com/stfc/goldilocks-ml/issues/95)) --
+use `uv run goldilocks magnetic-orderings --rank-with-mmace` from the CLI for
+ranking instead. Checksum verification and full troubleshooting:
+[mMACE setup](docs/mmace-setup.md).
+
+### Generate inputs from the command line
+
+Download the prediction models and default pseudopotential table, then generate
+inputs for the bundled silicon structure:
+
+```bash
+uv run goldilocks assets install default
+uv run goldilocks run src/goldilocks_core/examples/structures/Si.cif --out si-run
+```
+
+Open `si-run/scf.in` to see the input. The directory also contains the
+pseudopotential file, a submission script, and `goldilocks.json` (full
+provenance for every setting).
+
+Treat the recommended settings as a starting point: review warnings and check
+convergence for your calculation. The [quickstart](docs/quickstart.md) explains
+the output and how to run it.
+
+## Guides and reference
+
+- [First calculation](docs/quickstart.md) — generate, check, and run an input.
+- [Python API](docs/tutorial.md) — use Goldilocks in a script.
+- [Recommendations](docs/science.md) — understand the choices and their limits.
+- [Pseudopotentials](docs/pseudopotentials.md) — choose a table and understand
+  automatic selection.
+- [CLI reference](docs/cli.md) — commands and options.
+- [mMACE setup](docs/mmace-setup.md) — enable the ML-backed magnetism
+  features.
+- [Scientific conventions](docs/conventions.md) — units and numerical
+  definitions.
+- [Contributing](docs/architecture.md) — code layout and development checks.
+
+## Licence
+
+Code: [BSD 3-Clause](LICENSE). Documentation under `docs/` and example
+structures: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+Downloaded pseudopotentials retain their
+[upstream licences](docs/pseudopotentials.md#licences-and-citations).

goldilocks_core-0.1.0/README.md

@@ -0,0 +1,114 @@
+# goldilocks-core
+
+Goldilocks recommends settings for density functional theory (DFT) calculations
+and generates Quantum ESPRESSO input files (SCF, DOS, relaxation, and
+variable-cell relaxation) from a crystal structure.
+
+## Installation
+
+Not published to PyPI yet -- clone the repository. Install
+[uv](https://docs.astral.sh/uv/getting-started/installation/) first:
+
+```bash
+git clone https://github.com/junwen94/goldilocks-core.git
+cd goldilocks-core
+uv sync
+```
+
+## Try it
+
+### Start the Workbench
+
+With Node.js 24 or newer installed, run:
+
+```bash
+uv sync --extra http
+npm --prefix web ci
+uv run goldilocks assets install workbench
+uv run --extra http poe workbench
+```
+
+The asset step installs the models and pseudopotential tables. Open
+**http://127.0.0.1:5173**, upload a CIF or POSCAR, review the recommended
+settings, and download the generated inputs.
+
+For a built frontend instead, stop the development servers and run:
+
+```bash
+uv run --extra http poe stage
+```
+
+Then open **http://127.0.0.1:8000**. See the [Workbench guide](web/README.md)
+for Docker and development checks.
+
+#### With mMACE (ML-backed magnetism features)
+
+Without any extra setup, magnetism classification (`is_magnetic`) and
+magnetic-ordering ranking run at a heuristic/LLM tier. To get the real ML
+tier, install `mace`/`e3nn`/`sphericart` and a checkpoint file once, manually
+-- none of this can ever be a `pip`/`uv` extra (the `mace` fork it needs has
+no PyPI release):
+
+```bash
+uv pip install ase==3.28.0 e3nn==0.4.4 sphericart==1.0.9 sphericart-torch==1.0.9
+uv pip install "mace-torch @ git+https://github.com/CheukHinHoJerry/mace.git@19cdf6692c48e068a24e06cfe1ffc670e8aea3dd"
+mkdir -p ~/.local/share/goldilocks/mmace
+curl -L -o ~/.local/share/goldilocks/mmace/mace_matpes_pbe_baseline_run-3.model \
+  https://data-collections.psdi.ac.uk/api/records/1g8rw-q8128/files/mace_matpes_pbe_baseline_run-3.model/content
+export GOLDILOCKS_MACE_BACKBONE=~/.local/share/goldilocks/mmace/mace_matpes_pbe_baseline_run-3.model
+```
+
+Then start the Workbench as above **in the same shell** (the backend only
+picks up `GOLDILOCKS_MACE_BACKBONE` if it's set before launch). Load a
+magnetic structure (e.g.
+`src/goldilocks_core/examples/structures/Fe_bcc.cif`) and check the
+**Analysis** column's "is magnetic" field: its caption switches to
+**"Goldilocks-ML prediction"** once the `ml` tier is live.
+
+Two gotchas worth knowing up front: `uv sync` silently removes the two
+manually-installed packages again (they're not in `uv.lock`) -- re-run the
+`uv pip install` lines above after any `uv sync`; and the Workbench's own
+"Run mMACE" ranking button is currently broken
+([stfc/goldilocks-ml#95](https://github.com/stfc/goldilocks-ml/issues/95)) --
+use `uv run goldilocks magnetic-orderings --rank-with-mmace` from the CLI for
+ranking instead. Checksum verification and full troubleshooting:
+[mMACE setup](docs/mmace-setup.md).
+
+### Generate inputs from the command line
+
+Download the prediction models and default pseudopotential table, then generate
+inputs for the bundled silicon structure:
+
+```bash
+uv run goldilocks assets install default
+uv run goldilocks run src/goldilocks_core/examples/structures/Si.cif --out si-run
+```
+
+Open `si-run/scf.in` to see the input. The directory also contains the
+pseudopotential file, a submission script, and `goldilocks.json` (full
+provenance for every setting).
+
+Treat the recommended settings as a starting point: review warnings and check
+convergence for your calculation. The [quickstart](docs/quickstart.md) explains
+the output and how to run it.
+
+## Guides and reference
+
+- [First calculation](docs/quickstart.md) — generate, check, and run an input.
+- [Python API](docs/tutorial.md) — use Goldilocks in a script.
+- [Recommendations](docs/science.md) — understand the choices and their limits.
+- [Pseudopotentials](docs/pseudopotentials.md) — choose a table and understand
+  automatic selection.
+- [CLI reference](docs/cli.md) — commands and options.
+- [mMACE setup](docs/mmace-setup.md) — enable the ML-backed magnetism
+  features.
+- [Scientific conventions](docs/conventions.md) — units and numerical
+  definitions.
+- [Contributing](docs/architecture.md) — code layout and development checks.
+
+## Licence
+
+Code: [BSD 3-Clause](LICENSE). Documentation under `docs/` and example
+structures: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+Downloaded pseudopotentials retain their
+[upstream licences](docs/pseudopotentials.md#licences-and-citations).

goldilocks_core-0.1.0/pyproject.toml

@@ -0,0 +1,266 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "goldilocks-core"
+version = "0.1.0"
+description = "Materials machine learning tools for recommending DFT calculation inputs."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    # v2: generation/quantum_espresso/namelists.py uses only ase.io.espresso_namelist's
+    # Namelist class (a flat-dict -> QE namelist-text formatter with no Atoms/magnetic-
+    # moment logic at all) -- not ase.io.espresso.write_espresso_in, and not the
+    # Espresso calculator, both of which derive/overwrite starting_magnetization from
+    # atoms.get_initial_magnetic_moments() whenever nspin==2, unconditionally clobbering
+    # any value already resolved by advisors/magnetic_config.py (verified against
+    # installed ase 3.28, 2026-09-14; goldilocks-core-design.md:4220's "only use ASE at
+    # the namelists.py translation layer" insertion point).
+    "ase>=3.28",
+    "numpy>=2.4.4",
+    "pandas>=2.0",
+    "pymatgen>=2026.3.23",
+    "requests>=2.32",
+    # The default k-points/metallicity models (QRF + CGCNN) are a core
+    # capability, so their ML stack ships in the base install (decision:
+    # stfc/goldilocks-core#32) -- via goldilocks-ml itself (v2 #11) rather
+    # than duplicating dscribe/matminer/scikit-learn/sklearn-quantile/
+    # torch/torch-geometric as separate pins here, which would drift the two
+    # packages apart the same way this exact torch pin already had to be
+    # unwound once (see goldilocks-ml's own comment: torch pinned to exactly
+    # 2.10.0, both the lowest release patched against
+    # CVE-2026-24747/GHSA-63cw-57p8-fm3p and the highest is_magnetic's
+    # manually-installed sphericart-torch==1.0.9 tolerates -- goldilocks-
+    # core's own prior `torch>=2.13.0` pin predated that finding and would
+    # have conflicted with it outright). goldilocks-ml 0.2.0 dropped its
+    # `models` extra entirely -- everything is now a hard dependency of
+    # plain `goldilocks-ml`, so there is nothing left to select here either.
+    # torch-geometric requires torch; the base install resolves torch from
+    # the CPU-only PyTorch index so the workbench image doesn't ship ~3.5G
+    # of unused CUDA/nvidia libraries. GPU hosts pull the CUDA wheel via an
+    # index override (see [tool.uv] below), not the default resolution.
+    "goldilocks-ml==0.2.3",
+    # v2: contracts/ is pydantic BaseModel end to end (validation, serialization,
+    # OpenAPI/capabilities schema generation) -- promoted from the http/mcp
+    # extras to a core dependency (goldilocks-core-design.md S12, already decided).
+    "pydantic>=2.12",
+]
+
+[project.optional-dependencies]
+http = ["fastapi", "uvicorn"]
+mcp = ["mcp"]
+# is_magnetic classification and mMACE-based magnetic-ordering ranking
+# (v2 #11, #87), additive on top of goldilocks-ml itself (a hard
+# dependency, already in the base install above). goldilocks-ml 0.2.0 (released
+# 2026-09-21) ships is_magnetic for real, so the base dependency above is
+# now functionally reachable -- but there is still, and will permanently
+# be, no installable extra for this repo to depend on here: goldilocks-ml
+# has decided against ever shipping a `magnetism` extra at all, because it
+# needs `mace` (a research collaborator's fork with no PyPI release, and
+# PyPI's own upload validation rejects a direct git dependency in a
+# published package's metadata regardless -- goldilocks-ml's own
+# deposits/magnetism/is_magnetic/mace_mlp/VENDORING_TODO.md has the full
+# story). is_magnetic needs the same manual `mace` install goldilocks-ml's
+# own README documents ("Use the is_magnetic classifier"); mMACE-based
+# ordering ranking additionally needs a manually-configured
+# GOLDILOCKS_MACE_BACKBONE checkpoint (advisors/magnetic_ordering_ml.py).
+# Neither of which any `pip install goldilocks-core[...]` extra could ever
+# make installable end-to-end -- this is a permanent, upstream-acknowledged
+# manual step, not a temporary gap this repo's own packaging can close.
+
+[project.scripts]
+goldilocks = "goldilocks_core.cli.core:main"
+
+[tool.poe.tasks.fmt]
+help = "Format src, tests, and scripts with ruff"
+cmd = "ruff format src tests scripts"
+
+[tool.poe.tasks.lint]
+help = "Check style and complexity, matching the CI gate"
+sequence = [
+    { cmd = "ruff check src tests scripts" },
+    { cmd = "ruff format --check src tests scripts" },
+    { cmd = "python scripts/check_complexity.py" },
+]
+
+[tool.poe.tasks.test]
+help = "Run the pytest suite"
+cmd = "pytest"
+
+[tool.poe.tasks.check]
+help = "Lint and test, the local pre-PR gate"
+sequence = [
+    { ref = "lint" },
+    { ref = "test" },
+]
+
+[tool.poe.tasks.serve]
+help = "Install assets and serve the Core HTTP backend on :8000"
+shell = """
+if curl -s -m1 http://127.0.0.1:8000/ >/dev/null 2>&1; then
+    echo "port 8000 is already in use - stop the other server (poe workbench, poe serve, or poe stage)" >&2
+    exit 1
+fi
+set -e
+goldilocks assets install workbench
+exec goldilocks serve http --host 127.0.0.1 --port 8000
+"""
+
+[tool.poe.tasks.stage]
+help = "Build the Workbench bundle and serve it from the Core HTTP process on :8000"
+shell = """
+if curl -s -m1 http://127.0.0.1:8000/ >/dev/null 2>&1; then
+    echo "port 8000 is already in use - stop the other server (poe workbench, poe serve, or poe stage)" >&2
+    exit 1
+fi
+set -e
+cd web && npm run build
+cd ..
+goldilocks assets install workbench
+exec goldilocks serve http --host 127.0.0.1 --port 8000 --static-root web/dist
+"""
+
+[tool.poe.tasks.workbench]
+help = "Install assets, serve the Core HTTP backend on :8000, and run the Vite dev server on :5173"
+shell = """
+if curl -s -m1 http://127.0.0.1:8000/ >/dev/null 2>&1; then
+    echo "port 8000 is already in use - stop the other server (poe workbench, poe serve, or poe stage)" >&2
+    exit 1
+fi
+set -e
+goldilocks assets install workbench
+goldilocks serve http --host 127.0.0.1 --port 8000 &
+backend_pid=$!
+trap 'kill "$backend_pid"' EXIT
+cd web && npm run dev
+"""
+
+[tool.poe.tasks.web-check]
+help = "Lint, unit-test, and build the Workbench frontend"
+shell = "cd web && npm run check"
+
+[dependency-groups]
+dev = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.6.0",
+    "mutmut>=3.8.0",
+    "poethepoet>=0.35",
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.11",
+]
+
+[tool.uv]
+package = true
+
+# PyTorch publishes CPU and CUDA wheels on separate indexes. Pin torch to the
+# CPU index so container/workbench builds don't ship ~3.5G of unused CUDA/nvidia
+# libraries. GPU hosts override with `uv sync --index-strategy unsafe-best-match
+# --extra-index-url https://download.pytorch.org/whl/cu130` (or set
+# UV_EXTRA_INDEX_URL to the cu130 index) to pull the CUDA wheel instead.
+# torch-geometric and other torch-* packages stay on PyPI; only torch itself is
+# re-sourced, since it's the one that drags in the nvidia/triton wheels.
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-cpu" },
+]
+
+[tool.pytest.ini_options]
+addopts = ["--strict-markers", "-ra"]
+pythonpath = ["src"]
+testpaths = ["tests"]
+markers = [
+    "unit: isolated behavior with controlled collaborators",
+    "integration: workflows crossing real package boundaries",
+    "physics: scientific invariants checked independently of implementation",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["goldilocks_core"]
+omit = ["/tmp/*"]
+
+[tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+show_missing = true
+skip_covered = true
+
+[tool.mutmut]
+# process_isolation = "forkserver" (mutmut >=3.8.0) routes every mutant's
+# fork/reap through one dedicated forkserver child, instead of the default
+# ForkRunner's os.wait() in the main process -- which reaps *any* child, so an
+# untracked pid (e.g. a leftover from the stats/generation phase) causes a
+# bare `self._running.pop(pid)` KeyError (stfc/goldilocks-core#76). The
+# forkserver's own reap loop explicitly ignores unknown pids instead of
+# crashing. Lowering --max-children (ci.yml, #77) only reduced how often the
+# race was hit; it could not fix a race that isn't about mutmut's own worker
+# concurrency in the first place.
+process_isolation = "forkserver"
+# source_paths creates parent directories for nested files; also_copy does not.
+# Copy nested test inputs without web/node_modules or build outputs.
+source_paths = [
+    "src/goldilocks_core",
+    "web/README.md",
+    ".agents/skills/use-goldilocks/references/workflows.md",
+    ".agents/skills/use-goldilocks/references/qe-scf-template.md",
+]
+# Documentation tests read these files and validate their relative links.
+also_copy = ["README.md", "LICENSE", "docs"]
+only_mutate = [
+    "src/goldilocks_core/advisors/pseudo_selection.py",
+    "src/goldilocks_core/functionals.py",
+    "src/goldilocks_core/generation/quantum_espresso/scf.py",
+    "src/goldilocks_core/kmesh.py",
+    "src/goldilocks_core/service/_pipeline.py",
+]
+mutate_only_covered_lines = false
+pytest_add_cli_args = ["-q"]
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "I", # baseline
+    "B",            # bugbear: real footguns
+    "UP",           # modern python; ceremony prevention
+    "C4",           # comprehensions over loops
+    "SIM",          # collapse ceremony
+    "RET",          # return discipline
+    "PIE",          # useless constructs
+    "PERF",         # needless work
+    "TID",          # import hygiene, banned modules
+    "RUF",          # ruff-specific: noqa discipline, mutable defaults
+    "BLE",          # no blind exception catches
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"goldilocks_core.contracts".msg = "the contracts package was dissolved; import from the domain module that defines the name"
+
+[tool.setuptools.package-data]
+goldilocks_core = [
+    "ml/registry.toml",
+    "assets/pseudopotentials/registry.toml",
+    "inputs/profiles/*.toml",
+    "examples/structures/*.cif",
+    "examples/structures/README.md",
+]
+
+
+[tool.ruff.lint.isort]
+combine-as-imports = true

goldilocks_core-0.1.0/setup.cfg

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

goldilocks_core-0.1.0/src/goldilocks_core/__init__.py

@@ -0,0 +1,17 @@
+"""goldilocks_core: DFT input advice and generation for Quantum ESPRESSO.
+
+Deliberately re-exports nothing (v2 epic 9, #9, cutover). v1's
+``__init__.py`` flattened its whole ``Service``/``compute``/
+``ComputeRequest`` surface here; v2 has no equivalent single facade to
+re-export, by design (``service/__init__.py``'s own docstring: "the
+public API stays flat" at *that* level, not this one). The real entry
+points are the packages themselves:
+
+- ``goldilocks_core.service`` -- ``advise``/``check``/``generate`` (and
+  the ``dos`` task's ``advise_dos``/``check_dos``/``generate_dos``), the
+  programmatic API
+- ``goldilocks_core.cli`` -- the ``goldilocks`` command-line entry point
+- ``goldilocks_core.server`` -- the HTTP and MCP transports
+"""
+
+from __future__ import annotations