spikeforge-hub 0.1.0__tar.gz

spikeforge_hub-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2018 Capsize LLC
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* 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.
+

spikeforge_hub-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: spikeforge-hub
+Version: 0.1.0
+Summary: Curated SNN model hub (catalog, cache, download, import) for spikeforge.
+Author-email: Capsize LLC <contact@capsizegames.com>
+Maintainer-email: Capsize LLC <contact@capsizegames.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/capsize-games/spikeforge
+Project-URL: Repository, https://github.com/capsize-games/spikeforge
+Keywords: spiking neural networks,model hub,huggingface,catalog
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: spikeforge~=0.3.0
+Requires-Dist: torch>=2.5
+Requires-Dist: huggingface_hub>=0.20
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# spikeforge
+
+[![CI](https://github.com/capsize-games/spikeforge/actions/workflows/ci.yml/badge.svg)](https://github.com/capsize-games/spikeforge/actions/workflows/ci.yml)
+[![Status: pre-1.0](https://img.shields.io/badge/status-pre--1.0-orange.svg)](OPEN_SOURCE_CHECKLIST.md)
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE)
+[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776AB.svg)](https://www.python.org/downloads/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/capsize-games/spikeforge/blob/main/CONTRIBUTING.md)
+[![Docs](https://img.shields.io/badge/docs-long--form%20reference-blue.svg)](documentation/README.md)
+
+A spiking-neural-network (SNN) toolkit built on
+[snnTorch](https://snntorch.readthedocs.io/) and PyTorch. Loads MNIST-style
+and neuromorphic event datasets, encodes them into rate, latency, delta, and
+random spikes, and trains, validates, exports, and deploys LIF networks —
+with a live browser dashboard served over WebSockets.
+
+> **Pre-1.0 and unpublished.** `install.sh` is the supported path today;
+> PyPI ships once the distributions are published. Before trusting any
+> number this produces, read
+> [Implications and boundaries](documentation/implications-and-boundaries.md).
+
+## Quickstart
+
+```bash
+git clone https://github.com/capsize-games/spikeforge.git
+cd spikeforge
+docker compose up --build
+```
+
+Open <http://localhost:8877> — the dashboard connects to the WebSocket on
+the same host and port. No separate backend or proxy to run.
+
+Prefer a local install, a headless example, or the CLI tools instead? See
+[Usage](documentation/usage.md) and [Quickstart](documentation/quickstart.md)
+for every path (`./install.sh`, local dev with Vite, `examples/`, and the
+eight `spikeforge-*` console scripts).
+
+## Features
+
+- **Encoding** — rate, latency, delta, and random spike coders.
+- **Training** — fully-connected and convolutional LIF networks with
+  surrogate-gradient cross-entropy, checkpointing, and opt-in AMP / gradient
+  checkpointing / truncated BPTT / multi-GPU.
+- **Topologies** — `fc_legacy`, `fc_small`, `conv_net`, `recurrent_net`, plus
+  the sequence presets `sequence_mlp` and `sequence_attn`.
+- **Datasets** — MNIST, Fashion-MNIST, KMNIST, QMNIST, USPS, EMNIST,
+  CIFAR-10, and (via the `events` extra) N-MNIST, DVS128 Gesture,
+  CIFAR10-DVS, and Spiking Speech Commands.
+- **Interpreter spine** — NIR export, an independent NIR interpreter, and
+  numerical drift validation.
+- **Introspection** — educational-mode `U[t]`/`I[t]`/`S[t]` traces,
+  trajectory metrics, and surrogate-derivative curves.
+- **Deployment** — a capability matrix, weight quantization, energy
+  accounting, and executable `reference`, `norse`, and `lava_loihi2`
+  backends.
+- **Model hub** — a curated, offline-first catalog plus optional live
+  Hugging Face search.
+- **Dashboard** — a React + TypeScript UI with training, introspection,
+  analysis, targets, energy, and hub panels, and seven guided walkthroughs.
+
+## Packages
+
+This repository is a single workspace that publishes four distributions:
+
+| Distribution | Import root | Purpose |
+|---|---|---|
+| `spikeforge` | `spikeforge` | Core package: encoders, topologies, training, simulator, NIR bridge, tracking |
+| `spikeforge-targets` | `spikeforge_targets` | Deployment targets, quantization, energy accounting, sparse event runtime |
+| `spikeforge-hub` | `spikeforge_hub` | Curated model hub and optional Hugging Face access |
+| `spikeforge-server` | `server` | FastAPI + WebSocket server and dashboard hosting |
+
+## Documentation
+
+This README stays short on purpose.
+[`documentation/`](documentation/README.md) is the full reference — install
+paths, the CLI tools, architecture, module layout, and the dev workflow —
+written for contributors and coding agents alike. Also see
+[COOKBOOK.md](COOKBOOK.md) for copy-pasteable recipes,
+[examples/](examples/) for runnable end-to-end scripts, and
+[plans/](plans/) for design documents and the roadmap.
+
+See [CONTRIBUTING.md](https://github.com/capsize-games/spikeforge/blob/main/CONTRIBUTING.md)
+and [rules.md](rules.md) before opening a pull request.
+
+## Citing
+
+If spikeforge is useful in your research, please cite it — see
+[CITATION.cff](CITATION.cff) (GitHub renders a "Cite this repository"
+button from it automatically).
+
+## License
+
+Released under the **BSD 3-Clause License** — see [LICENSE](LICENSE) and
+[AUTHORS](AUTHORS).

spikeforge_hub-0.1.0/README.md

@@ -0,0 +1,94 @@
+# spikeforge
+
+[![CI](https://github.com/capsize-games/spikeforge/actions/workflows/ci.yml/badge.svg)](https://github.com/capsize-games/spikeforge/actions/workflows/ci.yml)
+[![Status: pre-1.0](https://img.shields.io/badge/status-pre--1.0-orange.svg)](OPEN_SOURCE_CHECKLIST.md)
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE)
+[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776AB.svg)](https://www.python.org/downloads/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/capsize-games/spikeforge/blob/main/CONTRIBUTING.md)
+[![Docs](https://img.shields.io/badge/docs-long--form%20reference-blue.svg)](documentation/README.md)
+
+A spiking-neural-network (SNN) toolkit built on
+[snnTorch](https://snntorch.readthedocs.io/) and PyTorch. Loads MNIST-style
+and neuromorphic event datasets, encodes them into rate, latency, delta, and
+random spikes, and trains, validates, exports, and deploys LIF networks —
+with a live browser dashboard served over WebSockets.
+
+> **Pre-1.0 and unpublished.** `install.sh` is the supported path today;
+> PyPI ships once the distributions are published. Before trusting any
+> number this produces, read
+> [Implications and boundaries](documentation/implications-and-boundaries.md).
+
+## Quickstart
+
+```bash
+git clone https://github.com/capsize-games/spikeforge.git
+cd spikeforge
+docker compose up --build
+```
+
+Open <http://localhost:8877> — the dashboard connects to the WebSocket on
+the same host and port. No separate backend or proxy to run.
+
+Prefer a local install, a headless example, or the CLI tools instead? See
+[Usage](documentation/usage.md) and [Quickstart](documentation/quickstart.md)
+for every path (`./install.sh`, local dev with Vite, `examples/`, and the
+eight `spikeforge-*` console scripts).
+
+## Features
+
+- **Encoding** — rate, latency, delta, and random spike coders.
+- **Training** — fully-connected and convolutional LIF networks with
+  surrogate-gradient cross-entropy, checkpointing, and opt-in AMP / gradient
+  checkpointing / truncated BPTT / multi-GPU.
+- **Topologies** — `fc_legacy`, `fc_small`, `conv_net`, `recurrent_net`, plus
+  the sequence presets `sequence_mlp` and `sequence_attn`.
+- **Datasets** — MNIST, Fashion-MNIST, KMNIST, QMNIST, USPS, EMNIST,
+  CIFAR-10, and (via the `events` extra) N-MNIST, DVS128 Gesture,
+  CIFAR10-DVS, and Spiking Speech Commands.
+- **Interpreter spine** — NIR export, an independent NIR interpreter, and
+  numerical drift validation.
+- **Introspection** — educational-mode `U[t]`/`I[t]`/`S[t]` traces,
+  trajectory metrics, and surrogate-derivative curves.
+- **Deployment** — a capability matrix, weight quantization, energy
+  accounting, and executable `reference`, `norse`, and `lava_loihi2`
+  backends.
+- **Model hub** — a curated, offline-first catalog plus optional live
+  Hugging Face search.
+- **Dashboard** — a React + TypeScript UI with training, introspection,
+  analysis, targets, energy, and hub panels, and seven guided walkthroughs.
+
+## Packages
+
+This repository is a single workspace that publishes four distributions:
+
+| Distribution | Import root | Purpose |
+|---|---|---|
+| `spikeforge` | `spikeforge` | Core package: encoders, topologies, training, simulator, NIR bridge, tracking |
+| `spikeforge-targets` | `spikeforge_targets` | Deployment targets, quantization, energy accounting, sparse event runtime |
+| `spikeforge-hub` | `spikeforge_hub` | Curated model hub and optional Hugging Face access |
+| `spikeforge-server` | `server` | FastAPI + WebSocket server and dashboard hosting |
+
+## Documentation
+
+This README stays short on purpose.
+[`documentation/`](documentation/README.md) is the full reference — install
+paths, the CLI tools, architecture, module layout, and the dev workflow —
+written for contributors and coding agents alike. Also see
+[COOKBOOK.md](COOKBOOK.md) for copy-pasteable recipes,
+[examples/](examples/) for runnable end-to-end scripts, and
+[plans/](plans/) for design documents and the roadmap.
+
+See [CONTRIBUTING.md](https://github.com/capsize-games/spikeforge/blob/main/CONTRIBUTING.md)
+and [rules.md](rules.md) before opening a pull request.
+
+## Citing
+
+If spikeforge is useful in your research, please cite it — see
+[CITATION.cff](CITATION.cff) (GitHub renders a "Cite this repository"
+button from it automatically).
+
+## License
+
+Released under the **BSD 3-Clause License** — see [LICENSE](LICENSE) and
+[AUTHORS](AUTHORS).

spikeforge_hub-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+# PEP 621 packaging authority for the spikeforge-hub distribution (ARCH-0001 Phase 4).
+#
+# The distribution owns the ``spikeforge_hub`` import root, which absorbs the former
+# ``spikeforge.hub`` subpackage (catalog, cache, live Hugging Face access,
+# isolated download worker, and the inspect/compat/promote import funnel). It
+# depends on core, but core never depends on it. The optional
+# ``huggingface_hub`` dependency is a base dependency here, isolated in
+# ``spikeforge_hub.probe`` so the offline catalog still works without network access.
+#
+# ``spikeforge_hub/`` stays at its repository-root path and is exposed to the build via
+# the ``spikeforge_hub`` symlink next to this file (the same pattern the core, server,
+# and targets distributions use; see the ``packages.find`` table below).
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spikeforge-hub"
+version = "0.1.0"
+description = "Curated SNN model hub (catalog, cache, download, import) for spikeforge."
+# ``README.md`` and ``LICENSE`` are committed symlinks to the repository-root
+# files, mirroring the core, server, and targets distributions' metadata.
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Capsize LLC", email = "contact@capsizegames.com" },
+]
+maintainers = [
+    { name = "Capsize LLC", email = "contact@capsizegames.com" },
+]
+keywords = [
+    "spiking neural networks",
+    "model hub",
+    "huggingface",
+    "catalog",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    # The core library owns the interpreter/simulator, ``nir_bridge``, and the
+    # hub cache configuration; this distribution owns catalog/network I/O. The
+    # pin is a pre-1.0 compatible-release: >=0.3.0,<0.4.0.
+    "spikeforge~=0.3.0",
+    "torch>=2.5",
+    "huggingface_hub>=0.20",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+
+[project.scripts]
+spikeforge-hub = "spikeforge_hub.cli:main"
+# PT-W7 registry governance. The plan offers `spikeforge-registry` as a new
+# distribution *or* an extension of the hub; this "extend hub" option owns the
+# script here, so the promotion registry (stages/approver/signature/lineage)
+# ships without a separate import root.
+spikeforge-registry = "spikeforge_hub.registry_cli:main"
+
+[project.urls]
+Homepage = "https://github.com/capsize-games/spikeforge"
+Repository = "https://github.com/capsize-games/spikeforge"
+
+[tool.setuptools]
+zip-safe = false
+
+[tool.setuptools.packages.find]
+# Mirror the core/server/targets distributions: the `spikeforge_hub` import root is
+# exposed next to this file as a symlink to `../../spikeforge_hub` so the default
+# via-sdist `python -m build` produces a complete wheel. Discovery depends only
+# on this top-level package, never on core.
+where = ["."]
+include = ["spikeforge_hub*"]
+exclude = ["spikeforge", "server*", "spikeforge_targets*", "tests*"]
+
+[tool.setuptools.package-data]
+# The catalog and its curation policy are runtime data, not code: without
+# these lines a `pip install spikeforge-hub` wheel would ship `spikeforge_hub/` with no
+# `models.json`, so the offline catalog could not load.
+spikeforge_hub = ["models.json", "CURATION.md"]

spikeforge_hub-0.1.0/setup.cfg

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

spikeforge_hub-0.1.0/spikeforge_hub/CURATION.md

@@ -0,0 +1,77 @@
+# Hub catalog curation policy
+
+The shipped catalog [`models.json`](models.json) is a **curated allow-list**, not
+a directory of everything that exists. Every entry must be something the project
+can stand behind: a real source and a license that has actually been read. An
+invented repository id or an unnamed license is a fabrication and must never be
+committed here.
+
+The record schema is enforced by
+[`hub/entry.py`](entry.py:1) and validated on load by
+[`hub/catalog.py`](catalog.py:1); anything that fails validation is reported
+through `catalog.issues()` and dropped from `entries()` rather than silently
+accepted.
+
+## Adding a bundled entry
+
+A bundled artifact is authored by this project (for example a NIR graph rendered
+from a shipped topology preset). To add one:
+
+1. Add an entry object to [`models.json`](models.json) with `"source":
+   "bundled"`.
+2. Set the concrete SPDX id for **your** artifact (`"license":
+   "BSD-3-Clause"` for this project's own presets).
+3. Set `"topology"` to the shipped preset the graph is rendered from, and
+   `"input_shape"` to its expected input.
+4. Describe the provenance in `"notes"` so a reader can tell why it is bundled.
+
+## Adding a remote entry
+
+A remote entry (`"source": "url"` or `"source": "hf_repo"`) points at bytes
+somewhere else. To add one **you must verify the source first**:
+
+1. **Name a real repository or reference.** Use the exact, resolvable locator —
+   the full `url`, or the real `org/repo` id for `hf_repo`. Do not invent a
+   namespace or a "seed" repository id. If you cannot point at a real upstream,
+   there is no entry to add.
+2. **State a verified license.** Read the upstream license and put its concrete
+   SPDX-style id in `"license"` (for example `"Apache-2.0"`,
+   `"BSD-3-Clause"`, `"MIT"`). A compound term such as `"MIT OR Apache-2.0"` is
+   accepted. Free-text escapes — `"see upstream"`, `"unknown"`, `"TBD"` — are
+   rejected by validation.
+3. **Publish a checksum where one is available.** Prefer `"sha256"` (and
+   `"size_bytes"` when known) so a download can verify as `verified`. When the
+   source publishes no checksum, it is honest to omit it — the download then
+   reports as `unverified`, never as verified.
+
+## Unverified candidates must not be presented as ready
+
+If a candidate is known-but-not-yet-verified, it may be recorded **only** with
+the explicit marker:
+
+```json
+"license": "unverified-candidate"
+```
+
+That marker disables the entry: [`catalog.availability()`](catalog.py:106)
+reports it `available: false` with the named reason *"unverified candidate:
+upstream repository and license are not confirmed …"*, and it must never be
+described as ready to use. Candidates are a record of work to do, not a
+recommendation. When the real source and license are confirmed, replace the
+marker with the concrete SPDX id (and add a checksum where available); if the
+source cannot be verified, delete the entry.
+
+An `hf_repo` or `url` entry that omits a real locator, or whose `"license"` is
+free-text rather than a concrete id or the marker, fails validation and appears
+in `catalog.issues()` instead of in `entries()`.
+
+## Why the shipped catalog is small
+
+The catalog ships only artifacts the project can stand behind. The Hugging Face
+ingestion capability stays fully available — [`probe.py`](probe.py:1),
+[`hf_api.py`](hf_api.py:1), [`download_cli.py`](download_cli.py:1), and the
+`hub` extra let a user download any **vetted** repository they choose to add.
+The catalog itself is not the downloader; it is the list of things already
+checked.
+
+See also [`NOTICE.md`](../../../NOTICE.md) for the metadata-only weights policy.

spikeforge_hub-0.1.0/spikeforge_hub/__init__.py

@@ -0,0 +1,132 @@
+"""Public API for the curated model hub.
+
+The offline catalog, capability probe, cache, isolated download worker, and the
+inspect/import funnel are wired here. Live Hugging Face access and artifact
+import build on this core in later phases; anything unavailable is reported,
+never faked.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from spikeforge_hub import cache, probe
+from spikeforge_hub.catalog import (
+    entries,
+    get,
+    issues,
+    list_entries,
+    search,
+)
+from spikeforge_hub.download_cli import download_entry
+from spikeforge_hub.entry import HubEntry
+from spikeforge_hub.errors import (
+    HubArtifactError,
+    HubCatalogError,
+    HubDownloadCancelledError,
+    HubDownloadError,
+    HubError,
+    HubExtraMissingError,
+    HubImportError,
+)
+from spikeforge_hub.import_model import import_model as _run_import
+from spikeforge_hub.inspect import inspect_artifact, resolve_path
+from spikeforge_hub.registry import (
+    REGISTRY_SCHEMA_VERSION,
+    STAGES,
+    STATUSES,
+    Registry,
+    RegistryEntry,
+    lineage_report,
+    promote,
+    sign_entry,
+    verify_artifact,
+    verify_entry,
+)
+from spikeforge_hub.registry_errors import (
+    RegistryApprovalError,
+    RegistryCompatibilityError,
+    RegistryError,
+    RegistryIntegrityError,
+    RegistryLifecycleError,
+    RegistryPromotionError,
+    RegistrySchemaError,
+    RegistrySignatureError,
+    RegistryVersionError,
+)
+
+__all__ = [
+    "REGISTRY_SCHEMA_VERSION",
+    "STAGES",
+    "STATUSES",
+    "HubArtifactError",
+    "HubCatalogError",
+    "HubDownloadCancelledError",
+    "HubDownloadError",
+    "HubEntry",
+    "HubError",
+    "HubExtraMissingError",
+    "HubImportError",
+    "Registry",
+    "RegistryApprovalError",
+    "RegistryCompatibilityError",
+    "RegistryEntry",
+    "RegistryError",
+    "RegistryIntegrityError",
+    "RegistryLifecycleError",
+    "RegistryPromotionError",
+    "RegistrySchemaError",
+    "RegistrySignatureError",
+    "RegistryVersionError",
+    "available",
+    "catalog",
+    "download",
+    "entries",
+    "get",
+    "import_model",
+    "inspect",
+    "issues",
+    "lineage_report",
+    "promote",
+    "search",
+    "sign_entry",
+    "verify_artifact",
+    "verify_entry",
+]
+
+
+def available() -> bool:
+    """Return True when live Hugging Face access (the ``hub`` extra) works."""
+    return probe.available()
+
+
+def catalog() -> List[Dict[str, object]]:
+    """Return every entry card, with availability and cache state."""
+    return list_entries()
+
+
+def download(entry_id: str, dest: Optional[str] = None) -> Dict[str, Any]:
+    """Download ``entry_id`` synchronously and return the worker report.
+
+    The async :class:`~spikeforge_hub.downloads.HubDownloadManager` runs
+    the same worker in a child process with progress and cancellation.
+    """
+    entry = get(entry_id)
+    if entry is None:
+        raise HubDownloadError(entry_id, "unknown catalog entry")
+    return download_entry(entry, dest or cache.entry_dir(entry.id))
+
+
+def inspect(entry_id: str) -> Dict[str, Any]:
+    """Return the structural report for ``entry_id``'s resolved artifact."""
+    entry = get(entry_id)
+    if entry is None:
+        raise HubArtifactError(entry_id, "unknown catalog entry")
+    return inspect_artifact(resolve_path(entry)).to_dict()
+
+
+def import_model(
+    entry_id: str,
+    topology: Optional[str] = None,
+    promote: bool = True,
+) -> Dict[str, Any]:
+    """Inspect, classify, and (when compatible) promote a catalog artifact."""
+    return _run_import(entry_id=entry_id, topology=topology, promote=promote)