neuralspotx 0.6.4__tar.gz

neuralspotx-0.6.4/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Ambiq
+All rights reserved.
+
+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.

neuralspotx-0.6.4/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: neuralspotx
+Version: 0.6.4
+Summary: Python tooling and app bootstrap for neuralspotx
+Author-email: Ambiq <support@ambiq.com>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/AmbiqAI/neuralspotx
+Project-URL: Repository, https://github.com/AmbiqAI/neuralspotx
+Project-URL: Issues, https://github.com/AmbiqAI/neuralspotx/issues
+Project-URL: Changelog, https://github.com/AmbiqAI/neuralspotx/blob/main/CHANGELOG.md
+Keywords: embedded,firmware,ambiq,neuralspot,build-system
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Jinja2>=3.1
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# neuralspotx
+
+[![CI](https://github.com/AmbiqAI/neuralspotx/actions/workflows/ci.yml/badge.svg)](https://github.com/AmbiqAI/neuralspotx/actions/workflows/ci.yml)
+[![Pages](https://github.com/AmbiqAI/neuralspotx/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/AmbiqAI/neuralspotx/actions/workflows/deploy-pages.yml)
+[![Release](https://github.com/AmbiqAI/neuralspotx/actions/workflows/release.yml/badge.svg)](https://github.com/AmbiqAI/neuralspotx/actions/workflows/release.yml)
+
+`neuralspotx` is the NSX tooling repo.
+
+NSX is a lightweight bare-metal workflow for Ambiq targets. It provides:
+
+- the `nsx` CLI
+- packaged app templates
+- packaged CMake helpers
+- built-in board definitions
+- curated metadata for module and SDK selection
+
+The primary audience is app developers creating small, focused NSX applications
+for bring-up, profiling, validation, and simple demos.
+
+For contributor workflows such as releases, CI, and the Python API surface, use
+the docs site under `docs/`.
+
+## Documentation
+
+The main documentation lives in the docs site built from `docs/`.
+
+Install the docs toolchain:
+
+```bash
+cd <nsx-repo>
+uv sync --group docs
+```
+
+Run the docs site locally:
+
+```bash
+cd <nsx-repo>
+uv run --group docs zensical serve
+```
+
+Build the static site:
+
+```bash
+cd <nsx-repo>
+uv run --group docs zensical build
+```
+
+## Quick Start
+
+NSX uses an app-first flow. Each app is a self-contained project directory with
+vendored modules, board definitions, and build helpers.
+
+For app users, the cleanest install path is `pipx`:
+
+```bash
+pipx install neuralspotx
+nsx doctor
+nsx create-app hello_ap510 --board apollo510_evb
+```
+
+For contributors working from a source checkout:
+
+```bash
+cd <nsx-repo>
+uv sync
+source .venv/bin/activate
+nsx doctor
+nsx create-app hello_ap510 --board apollo510_evb
+```
+
+Build the app:
+
+```bash
+nsx configure --app-dir hello_ap510
+nsx build --app-dir hello_ap510
+```
+
+## Repo Scope
+
+This repo owns:
+
+- `src/neuralspotx`
+- packaged documentation and templates
+- packaged board definitions
+- CMake helper assets used by generated apps
+
+Built-in firmware modules are described by the packaged registry and fetched
+from their default upstream repos as needed. Normal app users create standalone
+app directories and let NSX manage module resolution, vendoring, configuration,
+build, flash, and view flows.

neuralspotx-0.6.4/README.md

@@ -0,0 +1,90 @@
+# neuralspotx
+
+[![CI](https://github.com/AmbiqAI/neuralspotx/actions/workflows/ci.yml/badge.svg)](https://github.com/AmbiqAI/neuralspotx/actions/workflows/ci.yml)
+[![Pages](https://github.com/AmbiqAI/neuralspotx/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/AmbiqAI/neuralspotx/actions/workflows/deploy-pages.yml)
+[![Release](https://github.com/AmbiqAI/neuralspotx/actions/workflows/release.yml/badge.svg)](https://github.com/AmbiqAI/neuralspotx/actions/workflows/release.yml)
+
+`neuralspotx` is the NSX tooling repo.
+
+NSX is a lightweight bare-metal workflow for Ambiq targets. It provides:
+
+- the `nsx` CLI
+- packaged app templates
+- packaged CMake helpers
+- built-in board definitions
+- curated metadata for module and SDK selection
+
+The primary audience is app developers creating small, focused NSX applications
+for bring-up, profiling, validation, and simple demos.
+
+For contributor workflows such as releases, CI, and the Python API surface, use
+the docs site under `docs/`.
+
+## Documentation
+
+The main documentation lives in the docs site built from `docs/`.
+
+Install the docs toolchain:
+
+```bash
+cd <nsx-repo>
+uv sync --group docs
+```
+
+Run the docs site locally:
+
+```bash
+cd <nsx-repo>
+uv run --group docs zensical serve
+```
+
+Build the static site:
+
+```bash
+cd <nsx-repo>
+uv run --group docs zensical build
+```
+
+## Quick Start
+
+NSX uses an app-first flow. Each app is a self-contained project directory with
+vendored modules, board definitions, and build helpers.
+
+For app users, the cleanest install path is `pipx`:
+
+```bash
+pipx install neuralspotx
+nsx doctor
+nsx create-app hello_ap510 --board apollo510_evb
+```
+
+For contributors working from a source checkout:
+
+```bash
+cd <nsx-repo>
+uv sync
+source .venv/bin/activate
+nsx doctor
+nsx create-app hello_ap510 --board apollo510_evb
+```
+
+Build the app:
+
+```bash
+nsx configure --app-dir hello_ap510
+nsx build --app-dir hello_ap510
+```
+
+## Repo Scope
+
+This repo owns:
+
+- `src/neuralspotx`
+- packaged documentation and templates
+- packaged board definitions
+- CMake helper assets used by generated apps
+
+Built-in firmware modules are described by the packaged registry and fetched
+from their default upstream repos as needed. Normal app users create standalone
+app directories and let NSX manage module resolution, vendoring, configuration,
+build, flash, and view flows.

neuralspotx-0.6.4/pyproject.toml

@@ -0,0 +1,103 @@
+[project]
+name = "neuralspotx"
+version = "0.6.4"
+description = "Python tooling and app bootstrap for neuralspotx"
+requires-python = ">=3.10"
+license = {text = "BSD-3-Clause"}
+readme = "README.md"
+authors = [
+    {name = "Ambiq", email = "support@ambiq.com"},
+]
+keywords = ["embedded", "firmware", "ambiq", "neuralspot", "build-system"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Embedded Systems",
+    "Typing :: Typed",
+]
+dependencies = [
+    "Jinja2>=3.1",
+    "PyYAML>=6.0",
+]
+
+[project.scripts]
+nsx = "neuralspotx.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/AmbiqAI/neuralspotx"
+Repository = "https://github.com/AmbiqAI/neuralspotx"
+Issues = "https://github.com/AmbiqAI/neuralspotx/issues"
+Changelog = "https://github.com/AmbiqAI/neuralspotx/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+docs = [
+    "mkdocs-material>=9.0",
+    "pymdown-extensions>=10.15",
+    "zensical>=0.0.11",
+]
+lint = [
+    "ruff>=0.11.0",
+]
+test = [
+    "hypothesis>=6.0",
+    "pytest>=8.0",
+    "pytest-timeout>=2.3",
+]
+examples = [
+    # Host-side tools for example apps (e.g. usb_rpc rpc_host.py).
+    # grpcio-tools bundles protoc + a matching protobuf, eliminating
+    # version-mismatch errors between system protoc and the Python package.
+    # Run: uv sync --group examples
+    "pyserial>=3.5",
+    "grpcio-tools>=1.70",
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["neuralspotx", "neuralspotx.*"]
+
+[tool.setuptools.package-data]
+neuralspotx = ["py.typed", "templates/external_app/**/*", "cmake/**/*", "boards/**/*"]
+"neuralspotx.data" = ["*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+preview = true
+
+[tool.ruff.lint]
+# Enable preview to pick up PLW1514 ("unspecified-encoding"), which
+# flags `open(...)`, `Path.read_text(...)`, `Path.write_text(...)`,
+# etc. without an explicit `encoding=` argument. This protects us
+# from a recurrence of the R17/Windows mojibake bug, where the
+# default locale encoding (cp1252 on Windows) silently corrupted an
+# em-dash in a generated CMake file.
+extend-select = [
+    "PLW1514",  # unspecified-encoding
+]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]

neuralspotx-0.6.4/setup.cfg

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

neuralspotx-0.6.4/src/neuralspotx/__init__.py

@@ -0,0 +1,171 @@
+"""Canonical Python package for neuralspotx tooling.
+
+The names exposed here form the **public Python API** of NSX. Anything
+importable from a private ``_<name>`` module is, by convention,
+internal and may change without notice.
+
+See ``docs/reference/public-api.md`` for the canonical list with
+stability tiers. ``tests/test_public_surface_doc.py`` keeps the doc
+and ``__all__`` from drifting.
+"""
+
+from ._errors import (
+    NSXCacheError,
+    NSXConfigError,
+    NSXError,
+    NSXGitError,
+    NSXIntegrityError,
+    NSXLockError,
+    NSXModuleError,
+    NSXResolutionError,
+    NSXTimeoutError,
+    NSXToolchainError,
+)
+from ._io import Emitter, Event, default_emitter
+from .api import (
+    AppActionRequest,
+    AppBuildRequest,
+    AppCleanRequest,
+    AppCreateRequest,
+    AppFlashRequest,
+    AppLockRequest,
+    AppOutdatedRequest,
+    AppSyncRequest,
+    AppUpdateRequest,
+    AppViewRequest,
+    ModuleChangeRequest,
+    ModuleInitRequest,
+    ModuleRegisterRequest,
+    ModuleUpdateRequest,
+    add_module,
+    build_app,
+    cache_info,
+    clean_app,
+    clean_cache,
+    configure_app,
+    create_app,
+    describe_module,
+    doctor,
+    find_app_root,
+    flash_app,
+    generate_sbom,
+    init_module,
+    list_modules,
+    load_registry,
+    lock_app,
+    outdated_app,
+    register_module,
+    registry_module_project,
+    remove_module,
+    resolve_app_dir,
+    search_modules,
+    starter_profile,
+    sync_app,
+    update_app,
+    update_modules,
+    validate_module_metadata,
+    view_app,
+)
+from .models import (
+    CacheCleanResult,
+    CacheEntry,
+    CacheInfo,
+    CommandCategory,
+    CommandHint,
+    CommandScope,
+    DiscoveryRecord,
+    DoctorCheck,
+    DoctorReport,
+    ModuleChange,
+    OutdatedModule,
+    OutdatedReport,
+    OutdatedSkip,
+    SearchMatch,
+    SearchResult,
+)
+from .nsx_lock import LockKind, NsxLock, ResolvedModule
+from .operations import OutdatedStatus, ProfileStatus
+
+__all__ = [
+    # Request dataclasses
+    "AppActionRequest",
+    "AppBuildRequest",
+    "AppCleanRequest",
+    "AppCreateRequest",
+    "AppFlashRequest",
+    "AppLockRequest",
+    "AppOutdatedRequest",
+    "AppSyncRequest",
+    "AppUpdateRequest",
+    "AppViewRequest",
+    "ModuleChangeRequest",
+    "ModuleInitRequest",
+    "ModuleRegisterRequest",
+    "ModuleUpdateRequest",
+    # Result / data models
+    "CacheCleanResult",
+    "CacheEntry",
+    "CacheInfo",
+    "CommandCategory",
+    "CommandHint",
+    "CommandScope",
+    "DiscoveryRecord",
+    "DoctorCheck",
+    "DoctorReport",
+    "ModuleChange",
+    "OutdatedModule",
+    "OutdatedReport",
+    "OutdatedSkip",
+    "SearchMatch",
+    "SearchResult",
+    # Lock model + enums
+    "LockKind",
+    "NsxLock",
+    "OutdatedStatus",
+    "ProfileStatus",
+    "ResolvedModule",
+    # Errors
+    "NSXCacheError",
+    "NSXConfigError",
+    "NSXError",
+    "NSXGitError",
+    "NSXIntegrityError",
+    "NSXLockError",
+    "NSXModuleError",
+    "NSXResolutionError",
+    "NSXTimeoutError",
+    "NSXToolchainError",
+    # Structured emitter
+    "Emitter",
+    "Event",
+    "default_emitter",
+    # API callables
+    "add_module",
+    "build_app",
+    "cache_info",
+    "clean_app",
+    "clean_cache",
+    "configure_app",
+    "create_app",
+    "describe_module",
+    "doctor",
+    "find_app_root",
+    "flash_app",
+    "generate_sbom",
+    "init_module",
+    "list_modules",
+    "lock_app",
+    "load_registry",
+    "outdated_app",
+    "registry_module_project",
+    "register_module",
+    "remove_module",
+    "resolve_app_dir",
+    "search_modules",
+    "starter_profile",
+    "sync_app",
+    "update_app",
+    "update_modules",
+    "validate_module_metadata",
+    "view_app",
+]

neuralspotx-0.6.4/src/neuralspotx/_errors.py

@@ -0,0 +1,126 @@
+"""NSX exception hierarchy.
+
+Lives in its own module (no NSX imports) so internal layers
+(``operations``, ``module_registry``, ``project_config``,
+``subprocess_utils``, ``tooling``) can ``raise NSX*Error(...)`` directly
+without pulling in :mod:`neuralspotx.api` and creating an import cycle.
+
+The public surface is re-exported from :mod:`neuralspotx.api` and
+:mod:`neuralspotx` so library consumers continue to write
+``from neuralspotx import NSXError`` exactly as before.
+"""
+
+from __future__ import annotations
+
+
+class NSXError(RuntimeError):
+    """Raised when an NSX workflow operation fails.
+
+    Library consumers catch typed errors via ``except NSXError:`` (or one
+    of the more specific subclasses below).  The CLI wrapper translates
+    these into a non-zero process exit code at the top level; embedders
+    handle them as ordinary Python exceptions.
+    """
+
+
+class NSXTimeoutError(NSXError):
+    """Raised when an NSX subprocess exceeded its ``timeout_s`` budget."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: str | None = None,
+        timeout_s: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.command = command
+        self.timeout_s = timeout_s
+
+
+class NSXConfigError(NSXError):
+    """Raised for invalid or missing app / registry configuration.
+
+    The optional ``field`` attribute names the offending YAML key path
+    (dot-separated, with ``[i]`` for list indices, e.g.
+    ``"modules[2].name"``) so structured callers can map an error back
+    to a specific location in ``nsx.yml`` without re-parsing the
+    message.
+    """
+
+    def __init__(self, message: str, *, field: str | None = None) -> None:
+        super().__init__(message)
+        self.field = field
+
+
+class NSXCacheError(NSXError):
+    """Raised when an on-disk NSX cache file is unreadable or has an
+    unsupported ``schema_version``.
+
+    Catch alongside :class:`NSXError` for general failure handling, or
+    specifically when offering remediation steps such as ``nsx cache
+    clean``.
+    """
+
+
+class NSXResolutionError(NSXError):
+    """Raised for git-ref resolution or lock-file consistency failures."""
+
+
+class NSXLockError(NSXError):
+    """Raised for failures in the per-app advisory-lock subsystem.
+
+    Covers both runtime acquisition failures (the platform lock
+    primitive errors out, the lock is held by another process in
+    non-blocking mode) and on-disk ``nsx.lock`` schema/format
+    incompatibilities surfaced by readers like ``sync`` and
+    ``outdated``.
+    """
+
+
+class NSXModuleError(NSXError):
+    """Raised for module-name lookup or dependency-closure failures."""
+
+
+class NSXIntegrityError(NSXModuleError):
+    """Raised when a vendored module's content hash does not match
+    the value recorded in ``nsx.lock``.
+
+    Surfaced primarily by ``nsx sync --frozen`` when the on-disk tree
+    has been mutated since the lock was written. Subclasses
+    :class:`NSXModuleError` so existing ``except NSXModuleError`` sites
+    continue to catch the failure.
+    """
+
+    def __init__(self, message: str, *, module: str | None = None) -> None:
+        super().__init__(message)
+        self.module = module
+
+
+class NSXGitError(NSXError):
+    """Raised for unsafe or rejected ``git`` operations.
+
+    Used by ``git_clone_at_commit`` to refuse registry URLs that name
+    disallowed transports such as ``ext::`` (arbitrary command
+    execution) or ``file://`` / ``file::`` (local-filesystem
+    redirection), which would otherwise bypass the registry's
+    intended ``http(s)``/``ssh``/``git`` allow-list.
+    """
+
+
+class NSXToolchainError(NSXError):
+    """Raised for missing or unsupported toolchain configuration."""
+
+
+__all__ = [
+    "NSXCacheError",
+    "NSXConfigError",
+    "NSXError",
+    "NSXGitError",
+    "NSXIntegrityError",
+    "NSXLockError",
+    "NSXModuleError",
+    "NSXResolutionError",
+    "NSXTimeoutError",
+    "NSXToolchainError",
+]