# neuralSPOT-X reference

Generated from the installed package: the public Python API, the CLI and the
configuration schemas.

## Python API

- neuralspotx.api.AppActionRequest (class, models)
- neuralspotx.api.AppBuildRequest (class, models)
- neuralspotx.api.AppCleanRequest (class, models)
- neuralspotx.api.AppCreateRequest (class, models)
- neuralspotx.api.AppFlashRequest (class, models)
- neuralspotx.api.AppLockRequest (class, models)
- neuralspotx.api.AppOutdatedRequest (class, models)
- neuralspotx.api.AppSyncRequest (class, models)
- neuralspotx.api.AppUpdateRequest (class, models)
- neuralspotx.api.AppViewRequest (class, models)
- neuralspotx.api.BoardCreateRequest (class, models)
- neuralspotx.models.CacheCleanResult (class, models)
- neuralspotx.models.CacheEntry (class, models)
- neuralspotx.models.CacheInfo (class, models)
- neuralspotx.models.CommandCategory (class, models)
- neuralspotx.models.CommandHint (class, models)
- neuralspotx.models.CommandScope (class, models)
- neuralspotx.models.DiscoveryRecord (class, models)
- neuralspotx.models.DoctorCheck (class, models)
- neuralspotx.models.DoctorReport (class, models)
- neuralspotx.Emitter (attribute, emitters)
- neuralspotx.Event (class, emitters)
- neuralspotx.models.FlashResult (class, models)
- neuralspotx.nsx_lock.LockKind (class, models)
- neuralspotx.models.ModuleChange (class, models)
- neuralspotx.api.ModuleChangeRequest (class, models)
- neuralspotx.api.ModuleInitRequest (class, models)
- neuralspotx.api.ModuleRegisterRequest (class, models)
- neuralspotx.api.ModuleUpdateRequest (class, models)
- neuralspotx.NSXCacheError (class, errors)
- neuralspotx.NSXConfigError (class, errors)
- neuralspotx.NSXError (class, errors)
- neuralspotx.NSXGitError (class, errors)
- neuralspotx.NSXIntegrityError (class, errors)
- neuralspotx.NSXLockError (class, errors)
- neuralspotx.NSXModuleError (class, errors)
- neuralspotx.NSXResolutionError (class, errors)
- neuralspotx.NSXTimeoutError (class, errors)
- neuralspotx.NSXToolchainError (class, errors)
- neuralspotx.nsx_lock.NsxLock (class, models)
- neuralspotx.models.OutdatedModule (class, models)
- neuralspotx.models.OutdatedReport (class, models)
- neuralspotx.models.OutdatedSkip (class, models)
- neuralspotx.operations.OutdatedStatus (class, models)
- neuralspotx.operations.ProfileStatus (class, models)
- neuralspotx.models.ResetResult (class, models)
- neuralspotx.nsx_lock.ResolvedModule (class, models)
- neuralspotx.models.SearchMatch (class, models)
- neuralspotx.models.SearchResult (class, models)
- neuralspotx.api.add_module (function, functions)
- neuralspotx.api.build_app (function, functions)
- neuralspotx.api.cache_info (function, functions)
- neuralspotx.api.clean_app (function, functions)
- neuralspotx.api.clean_cache (function, functions)
- neuralspotx.api.configure_app (function, functions)
- neuralspotx.api.create_app (function, functions)
- neuralspotx.api.create_board (function, functions)
- neuralspotx.default_emitter (function, emitters)
- neuralspotx.api.describe_module (function, functions)
- neuralspotx.api.doctor (function, functions)
- neuralspotx.api.find_app_root (function, functions)
- neuralspotx.api.flash_app (function, functions)
- neuralspotx.api.generate_sbom (function, functions)
- neuralspotx.api.init_module (function, functions)
- neuralspotx.api.list_modules (function, functions)
- neuralspotx.api.load_registry (function, functions)
- neuralspotx.api.lock_app (function, functions)
- neuralspotx.api.outdated_app (function, functions)
- neuralspotx.api.register_module (function, functions)
- neuralspotx.api.registry_module_project (function, functions)
- neuralspotx.api.remove_module (function, functions)
- neuralspotx.api.reset_target (function, functions)
- neuralspotx.api.resolve_app_dir (function, functions)
- neuralspotx.api.search_modules (function, functions)
- neuralspotx.api.starter_profile (function, functions)
- neuralspotx.api.sync_app (function, functions)
- neuralspotx.api.update_app (function, functions)
- neuralspotx.api.update_modules (function, functions)
- neuralspotx.api.validate_module_metadata (function, functions)
- neuralspotx.api.view_app (function, functions)

## CLI

- nsx add (alias for nsx module add): Alias for `nsx module add`
    module: Module name to add
    --app-dir: App directory containing nsx.yml
    --local: Mark the module as local (mirrored from external path; ignored by git)
    --vendored: Scaffold a vendored module under modules/<name>/ (committed in this app's git; never touched by `nsx sync`)
    --path: Use an external linked checkout at DIR (source: { path: DIR })
    --board: Scope the dependency to BOARD (repeatable; subset of supported targets)
    --dry-run: Show changes without writing
- nsx board: Inspect packaged boards and scaffold custom boards
- nsx board create: Scaffold a custom board that inherits an EVB
    name: Name for the new custom board
    --from: Parent EVB to inherit from (e.g. apollo510_evb)
    --app-dir: Application directory (defaults to the nearest app root)
    --force: Overwrite an existing board directory
    --json: Emit machine-readable JSON instead of human-readable text
- nsx board list: List available boards
    --tier: Filter by board tier (e.g. 'evb', 'custom')
    --registered-only: Only show boards registered in the packaged build table
    --json: Emit machine-readable JSON instead of human-readable text
- nsx board show: Show details for a single board
    board: Board name (e.g. apollo510_evb)
    --json: Emit machine-readable JSON instead of human-readable text
- nsx build: Build a generated NSX app
    app: App name or directory (overrides --app-dir; resolved under ./ and ./examples)
    --app-dir: App directory containing nsx.yml
    --board: Override board from nsx.yml
    --build-dir: Build directory override
    --toolchain: Toolchain override (gcc, armclang, atfe)
    --sdk-root: Optional out-of-tree AmbiqSuite root passed as NSX_AMBIQSUITE_ROOT_OVERRIDE
    --target: Optional explicit build target
    --jobs: Parallel build jobs
    --update: Re-resolve module constraints to upstream tip and re-vendor before building
    --frozen: When a (re)configure is needed (no build.ninja yet), error on any drift between nsx.yml, nsx.lock, and modules/ instead of correcting it; modules missing from modules/ are fetched at their locked revision and verified
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx cache: Inspect or clean neuralSPOT-X on-disk caches
- nsx cache clean: Remove every neuralSPOT-X cache
    --yes: Confirm deletion (required; without it the command is a dry-run)
- nsx cache info: Show cache location, entry count, and total size
    --json: Emit machine-readable JSON instead of human-readable text
- nsx clean: Clean a generated NSX app build directory
    app: App name or directory (overrides --app-dir; resolved under ./ and ./examples)
    --app-dir: App directory containing nsx.yml
    --board: Override board from nsx.yml
    --build-dir: Build directory override
    --toolchain: Toolchain override (gcc, armclang, atfe)
    --full: Remove the full build directory instead of only running the build-system clean target
    --reset: Reset the app to a freshly-cloned state: remove all build*/ directories, the synced modules/ tree, and the .nsx/ folder. Use this before `git pull` to force `nsx configure` to re-sync from scratch.
    --force: With --reset, discard locally-modified files under modules/ without prompting
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx commands: Show the NSX command graph for users and agents
    --json: Emit the full command graph as machine-readable JSON
- nsx configure: Configure a generated NSX app with CMake
    app: App name or directory (overrides --app-dir; resolved under ./ and ./examples)
    --app-dir: App directory containing nsx.yml
    --board: Override board from nsx.yml
    --build-dir: Build directory override
    --toolchain: Toolchain override (gcc, armclang, atfe)
    --sdk-root: Optional out-of-tree AmbiqSuite root passed as NSX_AMBIQSUITE_ROOT_OVERRIDE
    --probe-serial: Optional SEGGER J-Link USB serial number to use for generated flash/view targets
    --frozen: Error on any drift between nsx.yml, nsx.lock, and modules/ instead of correcting it; modules missing from modules/ are fetched at their locked revision and verified
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx create-app: Create a new standalone NSX app project
    app_dir: App directory to create
    --board: Target board package suffix
    --soc: Target SoC package suffix (default inferred from board)
    --force: Allow writing into a non-empty app directory
    --no-bootstrap: Create the app without initializing starter modules
    --template: App template (default: Minimal hello-world app (SWO printf loop); npu-tflm: TFLite Micro inference on the Ethos-U85 NPU (Vela model harness, heliaRT ethos-u dispatch))
- nsx doctor: Check the local NSX toolchain environment
    --json: Emit the full doctor report as machine-readable JSON
- nsx flash: Build and flash a generated NSX app
    app: App name or directory (overrides --app-dir; resolved under ./ and ./examples)
    --app-dir: App directory containing nsx.yml
    --board: Override board from nsx.yml
    --build-dir: Build directory override
    --toolchain: Toolchain override (gcc, armclang, atfe)
    --target: Optional executable target to flash
    --sdk-root: Optional out-of-tree AmbiqSuite root passed as NSX_AMBIQSUITE_ROOT_OVERRIDE
    --probe-serial: Optional SEGGER J-Link USB serial number to use
    --jobs: Parallel build jobs
    --update: Re-resolve module constraints to upstream tip and re-vendor before flashing
    --frozen: When a (re)configure is needed, error on any drift between nsx.yml, nsx.lock, and modules/ instead of correcting it; modules missing from modules/ are fetched at their locked revision and verified. Note: passing --probe-serial always forces a reconfigure; --frozen only changes how the accompanying module sync behaves, not whether it runs.
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx list-modules (alias for nsx module list): Alias for `nsx module list`
    --app-dir: App directory containing nsx.yml; required unless --registry-only is used
    --registry-only: List all modules in the packaged registry without app-specific overrides
    --json: Emit machine-readable JSON instead of a table
- nsx lock: Resolve modules in nsx.yml to commits and write nsx.lock
    --app-dir: App directory containing nsx.yml
    --update: Re-resolve constraints to current upstream tip (otherwise reuses prior SHAs)
    --module: Only re-resolve the named module (may be repeated; implies --update)
    --check: Exit non-zero if nsx.lock is out of date with nsx.yml (do not write); useful in CI
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx module: Manage app-local NSX modules
- nsx module add: Add a direct dependency to an app
    module: Module name to add
    --app-dir: App directory containing nsx.yml
    --local: Mark the module as local (mirrored from external path; ignored by git)
    --vendored: Scaffold a vendored module under modules/<name>/ (committed in this app's git; never touched by `nsx sync`)
    --path: Use an external linked checkout at DIR (source: { path: DIR })
    --board: Scope the dependency to BOARD (repeatable; subset of supported targets)
    --dry-run: Show changes without writing
- nsx module describe: Show detailed metadata for one module
    module: Module name to describe
    --app-dir: Optional app directory containing nsx.yml; when provided, use the app-effective registry
    --json: Emit machine-readable JSON instead of human-readable text
- nsx module init: Create a standard custom-module skeleton
    module_dir: Directory to create for the module skeleton
    --name: Logical module name (defaults to the directory name)
    --type: NSX module type for the generated metadata
    --summary: One-line module summary to seed into nsx-module.yaml
    --version: Initial semantic version for the module
    --dependency: Required module dependency to add to the skeleton; repeat as needed
    --board: Compatible board to declare; repeat as needed (defaults to *)
    --soc: Compatible SoC to declare; repeat as needed (defaults to *)
    --toolchain: Compatible toolchain to declare; repeat as needed (defaults to arm-none-eabi-gcc)
    --force: Allow writing into a non-empty destination directory
- nsx module list: List modules from the packaged or app-effective registry
    --app-dir: App directory containing nsx.yml; required unless --registry-only is used
    --registry-only: List all modules in the packaged registry without app-specific overrides
    --json: Emit machine-readable JSON instead of a table
- nsx module register: Register and vendor an external module for one app
    module: Module name
    --metadata: Path to the module's nsx-module.yaml
    --project: Registry project key for this module
    --project-url: Override git project URL
    --project-revision: Override git project revision
    --project-path: Override git project path
    --project-local-path: Local filesystem path to vendor from
    --app-dir: App directory containing nsx.yml
    --override: Override existing module entry
    --dry-run: Show changes without writing
- nsx module remove: Disable a module for an app
    module: Module name to remove
    --app-dir: App directory containing nsx.yml
    --dry-run: Show changes without writing
- nsx module search: Search modules by intent, capability, or keyword
    query: Search query such as pmu, profiling, uart, or logging
    --app-dir: Optional app directory containing nsx.yml; when provided, use the app-effective registry and app target context
    --board: Optional board compatibility filter
    --soc: Optional SoC compatibility filter
    --toolchain: Optional toolchain compatibility filter
    --include-incompatible: Include matches that fail the active compatibility filters
    --json: Emit machine-readable JSON instead of human-readable text
- nsx module update: Refresh enabled modules to current registry revisions
    module: Optional single module to refresh
    --app-dir: App directory containing nsx.yml
    --dry-run: Show changes without writing
- nsx module validate: Validate an nsx-module.yaml file
    metadata: Path to the nsx-module.yaml file to validate
    --json: Emit machine-readable JSON instead of human-readable text
- nsx new (alias for nsx create-app): Alias for create-app
    app_dir: App directory to create
    --board: Target board package suffix
    --soc: Target SoC package suffix (default inferred from board)
    --force: Allow writing into a non-empty app directory
    --no-bootstrap: Create the app without initializing starter modules
    --template: App template (default: Minimal hello-world app (SWO printf loop); npu-tflm: TFLite Micro inference on the Ethos-U85 NPU (Vela model harness, heliaRT ethos-u dispatch))
- nsx outdated: Show git modules whose locked commit lags behind upstream
    --app-dir: App directory containing nsx.lock
    --exit-code: Exit non-zero if any modules are outdated (useful in CI)
    --json: Emit machine-readable JSON instead of the human-readable table
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx probes: List connected SEGGER J-Link debug probes
    --json: Emit machine-readable JSON instead of human-readable text
- nsx reset: Explicitly reset a target with SEGGER J-Link
    --device: SEGGER J-Link target device name
    --probe-serial: Optional SEGGER J-Link USB serial number to use
    --kind: Reset primitive
    --interface: Debug interface (default: SWD)
    --speed-khz: Debug interface speed in kHz
    --verify-reconnect: Reconnect after reset and fail if the target is unavailable
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx sbom: Generate a Software Bill of Materials from nsx.lock
    --app-dir: App directory containing nsx.lock
    --format: SBOM format (default: spdx — SPDX 2.3 JSON)
    --output, -o: Write SBOM to FILE instead of stdout
- nsx sync: Make modules/ exactly match nsx.lock
    --app-dir: App directory containing nsx.yml
    --frozen: Error on any drift between nsx.yml, nsx.lock, and modules/ instead of correcting it; modules missing from modules/ are fetched at their locked revision and verified
    --force: Re-vendor every module even if its content_hash matches the lock
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx update: Re-resolve constraints to upstream tip and sync modules
    --app-dir: App directory containing nsx.yml
    --module: Only update the named module (may be repeated)
    --yes: Confirm large updates non-interactively. Required when 3+ modules will move and stdin is not a tty.
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.
- nsx view: Open the SEGGER SWO viewer for a generated NSX app
    app: App name or directory (overrides --app-dir; resolved under ./ and ./examples)
    --app-dir: App directory containing nsx.yml
    --board: Override board from nsx.yml
    --build-dir: Build directory override
    --toolchain: Toolchain override (gcc, armclang, atfe)
    --sdk-root: Optional out-of-tree AmbiqSuite root passed as NSX_AMBIQSUITE_ROOT_OVERRIDE
    --probe-serial: Optional SEGGER J-Link USB serial number to use
    --frozen: When a (re)configure is needed, error on any drift between nsx.yml, nsx.lock, and modules/ instead of correcting it; modules missing from modules/ are fetched at their locked revision and verified. Note: passing --probe-serial always forces a reconfigure; --frozen only changes how the accompanying module sync behaves, not whether it runs.
    --reset-on-open: Force a target reset after opening the SWO viewer
    --no-reset-on-open: Open the SWO viewer without issuing the app reset target after attach
    --reset-delay-ms: Milliseconds to wait after opening the SWO viewer before issuing reset
    --duration: Stop the viewer after SECONDS instead of running until interrupted
    --capture: Line-stream the SWO output to FILE in addition to stdout
    --timeout: Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout.

## Configuration

### nsx.yml

- schema_version (int): Manifest schema version. NSX refuses a manifest it does not recognize.
- project.name (string): App name. Used for the CMake project and the default build directory.
- targets.default (string): Board built when --board is not given.
- targets.supported (list of string, or map of board to overrides): Boards this app may be built for. The map form accepts per-board soc, profile and toolchain overrides.
- target.board (string): Single-board shorthand, superseded by targets.
- toolchain (string): Default toolchain for every board unless a board overrides it.
- channel (string): Registry channel the app tracks.
- modules (list of module entries): Direct dependencies. A string is shorthand for a map with only name set.
- modules[].name (string): Module name as it appears in the registry.
- modules[].project (string): Registry project that provides the module, when it is ambiguous.
- modules[].revision (string): Tag, branch or commit constraint for this module.
- modules[].boards (list of string): Restrict the dependency to a subset of targets.supported.
- modules[].local (bool): Mirror the module from an external path on every sync.
- modules[].source (map): Exactly one of path (external directory), vendored (true, committed in this repo) or git (URL, with optional rev).
- module_registry.projects (map): App-local project overrides keyed by project name, each with url, revision, path or local_path.
- module_registry.modules (map): App-local module overrides keyed by module name, each with project, revision and optional metadata.
- tooling (map): Tool settings passed through to the generated build. Keys are preserved as written.
- features (map): Feature flags passed through to the generated build.
- profile (string): Starter profile the app was created from.
- profile_status (string): Maturity recorded for the starter profile.
- baseline (string): Set to none to skip the board's baseline module set.

### nsx-module.yaml

- schema_version (int): Module metadata schema version.
- module.name (string): Module name. Must match the name used in the registry and in nsx.yml.
- module.type (string): What kind of module this is. Drives resolution order and compatibility rules.
- module.version (string): Module version string.
- module.category (string): Grouping used by the module catalog.
- module.provider (string): Organization or project that supplies the module.
- support.ambiqsuite (bool): Whether the module builds against AmbiqSuite. NSX requires true.
- support.zephyr (bool): Whether the module ships a Zephyr integration. When true, integrations.zephyr becomes required.
- build.cmake.package (string): CMake package name the module exports.
- build.cmake.targets (list of string): CMake targets the module exports. Must be non-empty.
- depends.required (list of string): Modules that must be present. May be empty.
- depends.optional (list of string): Modules used when present. May be empty.
- compatibility.boards (list of string): Boards the module supports. Must be non-empty.
- compatibility.socs (list of string): SoCs the module supports. Must be non-empty.
- compatibility.toolchains (list of string): Toolchains the module supports. Must be non-empty.
- integrations.zephyr.path (string): Zephyr module directory. Required when support.zephyr is true.
- integrations.zephyr.module_yml (string): Path to the Zephyr module.yml. Required when support.zephyr is true.
- integrations.zephyr.kconfig (string): Path to the module's Kconfig. Required when support.zephyr is true.
- constraints.required_sdk_provider (string): SDK provider module this module must be built against.
- summary (string): One-line description shown in the module catalog.
- capabilities (list of string): What the module provides, for search and agent discovery.
- use_cases (list of string): Situations the module suits.
- anti_use_cases (list of string): Situations the module does not suit.
- agent_keywords (list of string): Extra search terms for agent tooling.
- example_refs (list of string): Examples that use the module.
- composition_hints (list of string): Modules this one is usually combined with.

### board.yaml

- schema_version (int): Board descriptor schema version.
- board.name (string): Board name as used by --board and by targets.supported.
- board.soc (string): SoC this board carries.
- board.tier (string): Board tier. Custom boards created from an EVB baseline record their own tier.
- board.registered (bool): Whether the board appears in nsx board list.
- sdk_provider (string): SDK provider module the board builds against.
- cpu.core (string): Arm core name, for example cortex-m55.
- cpu.float_abi (string): Floating-point ABI passed to the toolchain.
- cpu.abi (string): Full ABI triple used to select toolchain flags.
- toolchains (list of string): Toolchains the board supports.
- inherits (string): Board this descriptor inherits from. Only custom boards set it.
- overrides.toolchains (list of string): Delta applied to the inherited toolchain list, using +name to add and -name to remove. Only valid with inherits.

### nsx.lock

- schema_version (int): Lock schema version. NSX writes it on every lock; a lock that declares an older one is regenerated, and a lock missing it is read as the current version.
- targets (map of board to lock section): One resolution per board, so an app can be locked for several boards at once.
- targets.<board>.generated_at (string (ISO 8601)): When this section was resolved.
- targets.<board>.nsx_tool.version (string): neuralspotx version that produced the section.
- targets.<board>.manifest.path (string): Manifest the section was resolved from.
- targets.<board>.manifest.hash (string): Content hash of that manifest. A mismatch is the drift --frozen rejects.
- targets.<board>.target.board (string): Board this section resolves.
- targets.<board>.target.soc (string): SoC of that board.
- targets.<board>.target.toolchain (string): Toolchain the section was resolved for.
- targets.<board>.modules (map of module name to entry): The full resolved closure, not just the direct dependencies.
- modules.<name>.project (string): Registry project that provides the module.
- modules.<name>.kind (string): How the module was resolved, which decides what the resolved block carries.
- modules.<name>.constraint (string): Constraint the resolution satisfied.
- modules.<name>.resolved.url (string): Upstream repository. Present for git and unresolved kinds.
- modules.<name>.resolved.tag (string): Tag the commit carries, when the constraint matched one.
- modules.<name>.resolved.commit (string): Exact commit vendored. Present for git and unresolved kinds.
- modules.<name>.resolved.tool_version (string): neuralspotx version that supplied a packaged module.
- modules.<name>.resolved.vendored_at (string): Path under the app where the module is materialized.
- modules.<name>.resolved.content_hash (string): SHA-256 of the vendored tree. The SBOM reports this and sync verifies it.
- modules.<name>.resolved.acquired_at (string (ISO 8601)): When the module was fetched.

## Python API detail

# neuralspotx

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.

Every name here is Provisional until 1.0; see
https://ambiqai.github.io/neuralspotx/reference/releases/ for what that
means and how to pin. ``tests/test_public_surface_doc.py`` keeps the
published symbol catalog and ``__all__`` from drifting.

## neuralspotx.PathLike

`attribute` · `python`

```python
PathLike = str | Path
```

Source: `src/neuralspotx/api/_app.py:23`

## neuralspotx.EventKind

`attribute` · `python`

```python
EventKind = Literal['info', 'warn', 'error', 'step', 'line']
```

Source: `src/neuralspotx/_io.py:35`

## neuralspotx.Emitter

`attribute` · `python`

```python
Emitter = Callable[[Event], None]
```

Source: `src/neuralspotx/_io.py:59`

## neuralspotx.NSXError

`class` · `python`

```python
NSXError()
```

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.

Source: `src/neuralspotx/_errors.py:16`

## neuralspotx.NSXTimeoutError

`class` · `python`

```python
NSXTimeoutError(message: str, *, command: str | None = None, timeout_s: float | None = None) -> None
```

Raised when an NSX subprocess exceeded its ``timeout_s`` budget.

Source: `src/neuralspotx/_errors.py:26`

### neuralspotx.NSXTimeoutError.command

`attribute` · `python`

```python
command = command
```

Source: `src/neuralspotx/_errors.py:37`

### neuralspotx.NSXTimeoutError.timeout_s

`attribute` · `python`

```python
timeout_s = timeout_s
```

Source: `src/neuralspotx/_errors.py:38`

## neuralspotx.Event

`class` · `python`

```python
Event(kind: EventKind, message: str, data: dict[str, Any] = dict()) -> None
```

`dataclass`

One emitted event from the operations layer.

Source: `src/neuralspotx/_io.py:38`

### neuralspotx.Event.kind

`attribute` · `python`

```python
kind: EventKind
```

Event category.  ``info``/``step`` are progress;
``warn``/``error`` flag problems; ``line`` is raw
machine-readable output (e.g. a diagnostic row).

Source: `src/neuralspotx/_io.py:51`

### neuralspotx.Event.message

`attribute` · `python`

```python
message: str
```

The fully-formatted text that would have been printed.

Source: `src/neuralspotx/_io.py:52`

### neuralspotx.Event.data

`attribute` · `python`

```python
data: dict[str, Any] = field(default_factory=dict)
```

Optional structured payload for embedders that want to
act on the event without re-parsing the message.

Source: `src/neuralspotx/_io.py:53`

### neuralspotx.Event.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/_io.py:55`

## neuralspotx.NSXConfigError

`class` · `python`

```python
NSXConfigError(message: str, *, field: str | None = None) -> None
```

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.

Source: `src/neuralspotx/_errors.py:41`

### neuralspotx.NSXConfigError.field

`attribute` · `python`

```python
field = field
```

Source: `src/neuralspotx/_errors.py:53`

## neuralspotx.BoardDescriptor

`class` · `python`

```python
BoardDescriptor(
    name: str,
    tier: str,
    soc: str,
    sdk_provider: str,
    registered: bool,
    cpu: BoardCpu,
    toolchains: tuple[str, ...],
    path: Path,
) -> None
```

`dataclass`

Declarative metadata for a single board.

``registered`` controls whether the board participates in the legacy
``constants.DEFAULT_SOC_FOR_BOARD`` / ``BOARD_SDK_PROVIDER`` tables.
A board may ship a full package while remaining unregistered.

Source: `src/neuralspotx/board_descriptors.py:47`

### neuralspotx.BoardDescriptor.name

`attribute` · `python`

```python
name: str
```

Source: `src/neuralspotx/board_descriptors.py:56`

### neuralspotx.BoardDescriptor.tier

`attribute` · `python`

```python
tier: str
```

Source: `src/neuralspotx/board_descriptors.py:57`

### neuralspotx.BoardDescriptor.soc

`attribute` · `python`

```python
soc: str
```

Source: `src/neuralspotx/board_descriptors.py:58`

### neuralspotx.BoardDescriptor.sdk_provider

`attribute` · `python`

```python
sdk_provider: str
```

Source: `src/neuralspotx/board_descriptors.py:59`

### neuralspotx.BoardDescriptor.registered

`attribute` · `python`

```python
registered: bool
```

Source: `src/neuralspotx/board_descriptors.py:60`

### neuralspotx.BoardDescriptor.cpu

`attribute` · `python`

```python
cpu: BoardCpu
```

Source: `src/neuralspotx/board_descriptors.py:61`

### neuralspotx.BoardDescriptor.toolchains

`attribute` · `python`

```python
toolchains: tuple[str, ...]
```

Source: `src/neuralspotx/board_descriptors.py:62`

### neuralspotx.BoardDescriptor.path

`attribute` · `python`

```python
path: Path
```

Source: `src/neuralspotx/board_descriptors.py:63`

## neuralspotx.NSXCacheError

`class` · `python`

```python
NSXCacheError()
```

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``.

Source: `src/neuralspotx/_errors.py:56`

## neuralspotx.default_emitter

`function` · `python`

```python
default_emitter(event: Event) -> None
```

Write *event* to stderr (info/warn/error/step) or stdout (line).

Output is intentionally identical to the legacy ``print(message)``
behavior modulo the destination stream.

Source: `src/neuralspotx/_io.py:62`

## neuralspotx.NSXResolutionError

`class` · `python`

```python
NSXResolutionError()
```

Raised for git-ref resolution or lock-file consistency failures.

Source: `src/neuralspotx/_errors.py:66`

## neuralspotx.NSXLockError

`class` · `python`

```python
NSXLockError()
```

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``.

Source: `src/neuralspotx/_errors.py:70`

## neuralspotx.NSXModuleError

`class` · `python`

```python
NSXModuleError()
```

Raised for module-name lookup or dependency-closure failures.

Source: `src/neuralspotx/_errors.py:81`

## neuralspotx.NSXIntegrityError

`class` · `python`

```python
NSXIntegrityError(message: str, *, module: str | None = None) -> None
```

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.

Source: `src/neuralspotx/_errors.py:85`

### neuralspotx.NSXIntegrityError.module

`attribute` · `python`

```python
module = module
```

Source: `src/neuralspotx/_errors.py:97`

## neuralspotx.NSXGitError

`class` · `python`

```python
NSXGitError()
```

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.

Source: `src/neuralspotx/_errors.py:100`

## neuralspotx.NSXToolchainError

`class` · `python`

```python
NSXToolchainError()
```

Raised for missing or unsupported toolchain configuration.

Source: `src/neuralspotx/_errors.py:111`

---

# neuralspotx.api

Programmatic API for the NSX workflow.

Stable public surface for embedders. The actual implementations live in
sibling submodules (``_requests``, ``_app``, ``_modules``, ``_lock``,
``_cache``, ``_sbom``); this facade re-exports them so existing
``from neuralspotx.api import …`` imports keep working.

## neuralspotx.api.cache_info

`function` · `python`

```python
cache_info() -> CacheInfo
```

Return a snapshot of the NSX module artifact cache.

The result includes the cache root, an "is the cache disabled
via NSX_DISABLE_MODULE_CACHE" flag, and one
:class:`~neuralspotx.models.CacheEntry` per content-addressed
artifact directory. ``CacheInfo.total_size_bytes`` is computed
by walking each entry — best-effort, errors are silently ignored
per file. Performs no I/O on stdout.

Source: `src/neuralspotx/api/_cache.py:9`

## neuralspotx.api.generate_sbom

`function` · `python`

```python
generate_sbom(app_dir: PathLike, *, format: str = 'spdx') -> str
```

Generate a Software Bill of Materials for the app at *app_dir*.

Reads ``nsx.lock`` and emits a single JSON document describing
every vendored module by upstream URL, commit SHA, and
``content_hash``. The returned string is ready to write to disk
or pipe into another SBOM tool.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| app_dir | PathLike | Required | App root containing ``nsx.lock``. |
| format | str | 'spdx' | ``"spdx"`` for SPDX 2.3 JSON (default) or ``"cyclonedx"`` for CycloneDX 1.5 JSON. |

**Raises**

| Name | Description |
| --- | --- |
| NSXConfigError | ``nsx.lock`` is missing, or *format* is not one of ``{"spdx", "cyclonedx"}``. |

Source: `src/neuralspotx/api/_sbom.py:12`

## neuralspotx.api.load_registry

`function` · `python`

```python
load_registry() -> dict[str, Any]
```

`cached`

Return the packaged NSX registry with derived starter profiles.

The result is loaded from the installed ``registry.lock.yaml`` and cached
in-process. No network or git operations are performed.

Source: `src/neuralspotx/api/_registry.py:12`

## neuralspotx.api.create_board

`function` · `python`

```python
create_board(
    name: str | BoardCreateRequest,
    *,
    from_board: str | None = None,
    app_dir: PathLike = '.',
    force: bool = False,
    emit: Emitter | None = None,
) -> BoardDescriptor
```

Scaffold a custom board that inherits a registered EVB baseline.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| name | str \| BoardCreateRequest | Required | Either the new board identifier or a typed request object. |
| from_board | str \| None | None | Parent EVB to inherit from (required unless ``name`` is a :class:`BoardCreateRequest`). |
| app_dir | PathLike | '.' | App root under which ``boards/<name>/`` is written. |
| force | bool | False | Overwrite an existing ``boards/<name>/`` directory. |
| emit | Emitter \| None | None | Optional event sink for progress/next-step messages. |

**Returns**

| Name | Type | Description |
| --- | --- | --- |
|  | BoardDescriptor | The freshly parsed :class:`BoardDescriptor` for the new board. |

Source: `src/neuralspotx/api/_board.py:16`

## neuralspotx.api.AppCreateRequest

`class` · `python`

```python
AppCreateRequest(
    app_dir: PathLike,
    board: str = DEFAULT_BOARD,
    soc: str | None = None,
    force: bool = False,
    no_bootstrap: bool = False,
    template: str = 'default',
) -> None
```

`dataclass`

Request parameters for creating a new NSX app.

Source: `src/neuralspotx/api/_requests.py:18`

### neuralspotx.api.AppCreateRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

Target app root.

Source: `src/neuralspotx/api/_requests.py:31`

### neuralspotx.api.AppCreateRequest.board

`attribute` · `python`

```python
board: str = DEFAULT_BOARD
```

Target board identifier.

Source: `src/neuralspotx/api/_requests.py:32`

### neuralspotx.api.AppCreateRequest.soc

`attribute` · `python`

```python
soc: str | None = None
```

Optional SoC override. When omitted, NSX infers it from ``board``.

Source: `src/neuralspotx/api/_requests.py:33`

### neuralspotx.api.AppCreateRequest.force

`attribute` · `python`

```python
force: bool = False
```

Allow writing into a non-empty app directory.

Source: `src/neuralspotx/api/_requests.py:34`

### neuralspotx.api.AppCreateRequest.no_bootstrap

`attribute` · `python`

```python
no_bootstrap: bool = False
```

Skip starter-module initialization.

Source: `src/neuralspotx/api/_requests.py:35`

### neuralspotx.api.AppCreateRequest.template

`attribute` · `python`

```python
template: str = 'default'
```

App template name (see ``operations.APP_TEMPLATES``).

Source: `src/neuralspotx/api/_requests.py:36`

## neuralspotx.api.ModuleInitRequest

`class` · `python`

```python
ModuleInitRequest(
    module_dir: PathLike,
    module_name: str | None = None,
    module_type: str = 'runtime',
    summary: str | None = None,
    version: str = '0.1.0',
    dependencies: list[str] | None = None,
    boards: list[str] | None = None,
    socs: list[str] | None = None,
    toolchains: list[str] | None = None,
    force: bool = False,
) -> None
```

`dataclass`

Describe a custom-module skeleton to create.

Source: `src/neuralspotx/models/_requests.py:19`

### neuralspotx.api.ModuleInitRequest.module_dir

`attribute` · `python`

```python
module_dir: PathLike
```

Destination directory for the generated module.

Source: `src/neuralspotx/models/_requests.py:36`

### neuralspotx.api.ModuleInitRequest.module_name

`attribute` · `python`

```python
module_name: str | None = None
```

Manifest module name. Defaults to the destination directory name.

Source: `src/neuralspotx/models/_requests.py:37`

### neuralspotx.api.ModuleInitRequest.module_type

`attribute` · `python`

```python
module_type: str = 'runtime'
```

NSX module type written to ``nsx-module.yaml``.

Source: `src/neuralspotx/models/_requests.py:38`

### neuralspotx.api.ModuleInitRequest.summary

`attribute` · `python`

```python
summary: str | None = None
```

Human-readable module summary. A placeholder is generated when omitted.

Source: `src/neuralspotx/models/_requests.py:39`

### neuralspotx.api.ModuleInitRequest.version

`attribute` · `python`

```python
version: str = '0.1.0'
```

Initial semantic version written to the module metadata.

Source: `src/neuralspotx/models/_requests.py:40`

### neuralspotx.api.ModuleInitRequest.dependencies

`attribute` · `python`

```python
dependencies: list[str] | None = None
```

Required NSX module names, in declaration order.

Source: `src/neuralspotx/models/_requests.py:41`

### neuralspotx.api.ModuleInitRequest.boards

`attribute` · `python`

```python
boards: list[str] | None = None
```

Compatible board names. Defaults to all boards.

Source: `src/neuralspotx/models/_requests.py:42`

### neuralspotx.api.ModuleInitRequest.socs

`attribute` · `python`

```python
socs: list[str] | None = None
```

Compatible SoC names. Defaults to all SoCs.

Source: `src/neuralspotx/models/_requests.py:43`

### neuralspotx.api.ModuleInitRequest.toolchains

`attribute` · `python`

```python
toolchains: list[str] | None = None
```

Compatible toolchain names. Defaults to the NSX default toolchain.

Source: `src/neuralspotx/models/_requests.py:44`

### neuralspotx.api.ModuleInitRequest.force

`attribute` · `python`

```python
force: bool = False
```

Allow generation into an existing non-empty directory.

Source: `src/neuralspotx/models/_requests.py:45`

## neuralspotx.api.add_module

`function` · `python`

```python
add_module(
    app_dir: PathLike | ModuleChangeRequest,
    module: str | None = None,
    *,
    dry_run: bool = False,
    local: bool = False,
    vendored: bool = False,
    path: str | None = None,
    boards: tuple[str, ...] = (),
) -> list[ModuleChange]
```

Add a module to an app.

Source: `src/neuralspotx/api/_modules.py:22`

## neuralspotx.api.lock_app

`function` · `python`

```python
lock_app(
    app_dir: PathLike | AppLockRequest,
    *,
    update: bool = False,
    modules: list[str] | None = None,
    check: bool = False,
    quiet: bool = False,
    timeout_s: float | None = None,
    resolve_ttl_s: float | None = None,
    emit: Emitter | None = None,
) -> NsxLock
```

Resolve module constraints and write ``nsx.lock``.

Returns the resolved :class:`~neuralspotx.nsx_lock.NsxLock`. The
filesystem path to the lock file is available on ``lock.path``.
*timeout_s* applies per ``git`` / ``git ls-remote`` subprocess.
*resolve_ttl_s* overrides the ``NSX_RESOLVE_TTL`` env for this call
(e.g. ``1800`` for 30 min in long workflows; ``0`` to disable).

Source: `src/neuralspotx/api/_lock.py:22`

## neuralspotx.api.clean_cache

`function` · `python`

```python
clean_cache(*, dry_run: bool = False) -> CacheCleanResult
```

Delete every entry in the NSX module artifact cache.

With ``dry_run=True`` no entries are removed; the returned
:class:`~neuralspotx.models.CacheCleanResult.removed_count`
reflects how many entries *would* be removed by an unconditional
invocation. Performs no I/O on stdout.

Source: `src/neuralspotx/api/_cache.py:23`

## neuralspotx.api.starter_profile

`function` · `python`

```python
starter_profile(board: str) -> dict[str, Any] | None
```

Return the ``{board}_minimal`` starter profile, or ``None`` if absent.

Source: `src/neuralspotx/api/_registry.py:24`

## neuralspotx.api.create_app

`function` · `python`

```python
create_app(
    app_dir: PathLike | AppCreateRequest,
    *,
    board: str = DEFAULT_BOARD,
    soc: str | None = None,
    force: bool = False,
    no_bootstrap: bool = False,
    template: str = 'default',
    emit: Emitter | None = None,
) -> Path
```

Create a new NSX app project.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| app_dir | PathLike \| AppCreateRequest | Required | Either an app-root path or a typed request object. |
| board | str | DEFAULT_BOARD | Target board identifier. |
| soc | str \| None | None | Optional SoC override. |
| force | bool | False | Allow writing into a non-empty app directory. |
| no_bootstrap | bool | False | Skip starter-module initialization. |
| template | str | 'default' | App template name (see ``operations.APP_TEMPLATES``). |

**Returns**

| Name | Type | Description |
| --- | --- | --- |
|  | Path | The resolved app-root :class:`pathlib.Path`. Suitable for |
|  | Path | chaining into :func:`configure_app`, :func:`build_app`, etc. |

Source: `src/neuralspotx/api/_app.py:26`

## neuralspotx.api.registry_module_project

`function` · `python`

```python
registry_module_project(name: str) -> str | None
```

Resolve a module name to its owning project via the packaged registry.

Returns ``None`` when the module has no packaged registry entry (for
example, a local opaque module supplied by the caller).

Source: `src/neuralspotx/api/_registry.py:30`

## neuralspotx.api.BoardCreateRequest

`class` · `python`

```python
BoardCreateRequest(name: str, from_board: str, app_dir: PathLike = '.', force: bool = False) -> None
```

`dataclass`

Request parameters for scaffolding a custom board.

Source: `src/neuralspotx/api/_requests.py:39`

### neuralspotx.api.BoardCreateRequest.name

`attribute` · `python`

```python
name: str
```

New custom board identifier (becomes ``boards/<name>/``).

Source: `src/neuralspotx/api/_requests.py:50`

### neuralspotx.api.BoardCreateRequest.from_board

`attribute` · `python`

```python
from_board: str
```

Parent EVB whose SoC/provider/CPU facts are inherited.

Source: `src/neuralspotx/api/_requests.py:51`

### neuralspotx.api.BoardCreateRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike = '.'
```

App root under which ``boards/<name>/`` is written.

Source: `src/neuralspotx/api/_requests.py:52`

### neuralspotx.api.BoardCreateRequest.force

`attribute` · `python`

```python
force: bool = False
```

Overwrite an existing ``boards/<name>/`` directory.

Source: `src/neuralspotx/api/_requests.py:53`

## neuralspotx.api.AppActionRequest

`class` · `python`

```python
AppActionRequest(
    app_dir: PathLike,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    probe_serial: str | None = None,
    *,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
) -> None
```

`dataclass`

Base request for app-scoped actions.

``frozen`` and ``timeout_s`` are keyword-only so subclasses (e.g.
:class:`AppBuildRequest`) keep their existing positional argument
order — inserting a new positional field into this base class would
silently shift the meaning of positional construction like
``AppBuildRequest(app_dir, None, None, None, None, "all", 4)``.
Construct with ``AppBuildRequest(app_dir, target="all", jobs=4,
timeout_s=300)``.

Source: `src/neuralspotx/api/_requests.py:56`

### neuralspotx.api.AppActionRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

App directory containing ``nsx.yml``.

Source: `src/neuralspotx/api/_requests.py:90`

### neuralspotx.api.AppActionRequest.board

`attribute` · `python`

```python
board: str | None = None
```

Optional board override.

Source: `src/neuralspotx/api/_requests.py:91`

### neuralspotx.api.AppActionRequest.build_dir

`attribute` · `python`

```python
build_dir: PathLike | None = None
```

Optional build directory override.

Source: `src/neuralspotx/api/_requests.py:92`

### neuralspotx.api.AppActionRequest.toolchain

`attribute` · `python`

```python
toolchain: str | None = None
```

Optional toolchain override (``gcc``, ``armclang``).

Source: `src/neuralspotx/api/_requests.py:93`

### neuralspotx.api.AppActionRequest.probe_serial

`attribute` · `python`

```python
probe_serial: str | None = None
```

Source: `src/neuralspotx/api/_requests.py:94`

### neuralspotx.api.AppActionRequest.sdk_root

`attribute` · `python`

```python
sdk_root: PathLike | None = field(default=None, kw_only=True)
```

Optional out-of-tree AmbiqSuite root passed through as
``-DNSX_AMBIQSUITE_ROOT_OVERRIDE=...`` during CMake configure.

Source: `src/neuralspotx/api/_requests.py:95`

### neuralspotx.api.AppActionRequest.frozen

`attribute` · `python`

```python
frozen: bool = field(default=False, kw_only=True)
```

When a module sync is needed (fresh workspace, or an
existing build directory reconfiguring), verify ``modules/``
against ``nsx.lock`` and raise instead of silently
re-vendoring on any drift; modules missing from disk are
fetched at their locked revision and verified. Mirrors
``AppSyncRequest.frozen``.
Use this to iterate on a hand-patched vendored module
without ``configure``/``build``/``flash`` silently reverting
it on the next run.

Source: `src/neuralspotx/api/_requests.py:96`

### neuralspotx.api.AppActionRequest.timeout_s

`attribute` · `python`

```python
timeout_s: float | None = field(default=None, kw_only=True)
```

Per-subprocess wall-clock budget (seconds).  ``None``
disables the timeout.  When the budget elapses, the entire
child process group is SIGTERM/SIGKILL'd and
:class:`NSXError` is raised.

Source: `src/neuralspotx/api/_requests.py:97`

## neuralspotx.api.remove_module

`function` · `python`

```python
remove_module(
    app_dir: PathLike | ModuleChangeRequest,
    module: str | None = None,
    *,
    dry_run: bool = False,
) -> list[ModuleChange]
```

Remove a module from an app.

Source: `src/neuralspotx/api/_modules.py:60`

## neuralspotx.api.doctor

`function` · `python`

```python
doctor(*, emit: Emitter | None = None) -> DoctorReport
```

Run the NSX environment diagnostics.

Returns the structured :class:`DoctorReport`. Never raises on a
failed check — embedders are expected to inspect ``report.ok`` and
decide how to react. The CLI handler raises
:class:`~neuralspotx._errors.NSXToolchainError` so ``nsx doctor``
keeps its historic non-zero exit code.

Source: `src/neuralspotx/api/_app.py:74`

## neuralspotx.api.sync_app

`function` · `python`

```python
sync_app(
    app_dir: PathLike | AppSyncRequest,
    *,
    frozen: bool = False,
    force: bool = False,
    timeout_s: float | None = None,
    emit: Emitter | None = None,
) -> None
```

Materialise ``modules/`` so it exactly matches ``nsx.lock``.

*timeout_s* applies per individual ``git clone`` / ``git fetch``
invoked during the sync (not to the whole sync run).

Source: `src/neuralspotx/api/_lock.py:74`

## neuralspotx.api.update_modules

`function` · `python`

```python
update_modules(
    app_dir: PathLike | ModuleUpdateRequest,
    *,
    module: str | None = None,
    dry_run: bool = False,
) -> list[ModuleChange]
```

Refresh one or more enabled modules from the registry.

Source: `src/neuralspotx/api/_modules.py:86`

## neuralspotx.api.configure_app

`function` · `python`

```python
configure_app(
    app_dir: PathLike | AppActionRequest,
    *,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    probe_serial: str | None = None,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
    emit: Emitter | None = None,
) -> None
```

Configure an app build directory with CMake.

*timeout_s* sets a wall-clock budget for the underlying ``cmake``
subprocess; the whole process group is killed on timeout.

*frozen* verifies ``modules/`` against ``nsx.lock`` and raises on any
drift instead of silently re-vendoring — see :class:`AppActionRequest`.

Source: `src/neuralspotx/api/_app.py:88`

## neuralspotx.api.AppViewRequest

`class` · `python`

```python
AppViewRequest(
    app_dir: PathLike,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    probe_serial: str | None = None,
    reset_on_open: bool | None = None,
    reset_delay_ms: int = 400,
    duration_s: float | None = None,
    capture: PathLike | None = None,
    *,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
) -> None
```

`dataclass`

Request parameters for launching the SWO viewer.

Source: `src/neuralspotx/api/_requests.py:100`

### neuralspotx.api.AppViewRequest.reset_on_open

`attribute` · `python`

```python
reset_on_open: bool | None = None
```

When True, reset the target once the viewer
attaches. When False, attach without resetting. When None
(default), choose the board-appropriate policy.

Source: `src/neuralspotx/api/_requests.py:117`

### neuralspotx.api.AppViewRequest.reset_delay_ms

`attribute` · `python`

```python
reset_delay_ms: int = 400
```

Delay between attaching the viewer and issuing
the reset, in milliseconds.

Source: `src/neuralspotx/api/_requests.py:118`

### neuralspotx.api.AppViewRequest.duration_s

`attribute` · `python`

```python
duration_s: float | None = None
```

When set, terminate the viewer after this many
seconds so the command always returns (instead of running
until interrupted).

Source: `src/neuralspotx/api/_requests.py:119`

### neuralspotx.api.AppViewRequest.capture

`attribute` · `python`

```python
capture: PathLike | None = None
```

When set, line-stream the viewer's output to this file
in addition to stdout.

Source: `src/neuralspotx/api/_requests.py:120`

## neuralspotx.api.outdated_app

`function` · `python`

```python
outdated_app(app_dir: PathLike | AppOutdatedRequest, *, timeout_s: float | None = None) -> OutdatedReport
```

Report git modules whose locked commit lags the upstream constraint.

Returns an :class:`OutdatedReport` describing every git-hosted
module inspected (``checked``) and any that could not be resolved
(``skipped``). Callers that need machine-readable output should
use ``report.to_dict()``.
*timeout_s* applies per ``git ls-remote`` subprocess invoked while
comparing locked commits to upstream tips.

Source: `src/neuralspotx/api/_lock.py:101`

## neuralspotx.api.register_module

`function` · `python`

```python
register_module(
    app_dir: PathLike | ModuleRegisterRequest,
    module: str | None = None,
    *,
    metadata: PathLike | None = None,
    project: str | None = None,
    project_url: str | None = None,
    project_revision: str | None = None,
    project_path: str | None = None,
    project_local_path: PathLike | None = None,
    override: bool = False,
    dry_run: bool = False,
) -> ModuleChange
```

Register an app-local module override.

Source: `src/neuralspotx/api/_modules.py:110`

## neuralspotx.api.AppBuildRequest

`class` · `python`

```python
AppBuildRequest(
    app_dir: PathLike,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    probe_serial: str | None = None,
    target: str | None = None,
    jobs: int = 8,
    *,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
) -> None
```

`dataclass`

Request parameters for building an app.

Source: `src/neuralspotx/api/_requests.py:123`

### neuralspotx.api.AppBuildRequest.target

`attribute` · `python`

```python
target: str | None = None
```

Source: `src/neuralspotx/api/_requests.py:127`

### neuralspotx.api.AppBuildRequest.jobs

`attribute` · `python`

```python
jobs: int = 8
```

Source: `src/neuralspotx/api/_requests.py:128`

## neuralspotx.api.update_app

`function` · `python`

```python
update_app(
    app_dir: PathLike | AppUpdateRequest,
    *,
    modules: list[str] | None = None,
    timeout_s: float | None = None,
    emit: Emitter | None = None,
) -> None
```

Re-resolve module constraints to upstream tip and re-vendor.

Equivalent to ``nsx lock --update [--module ...] && nsx sync``.
*timeout_s* applies per individual ``git`` subprocess invoked
during the re-resolve and re-vendor phases.

Source: `src/neuralspotx/api/_lock.py:127`

## neuralspotx.api.AppFlashRequest

`class` · `python`

```python
AppFlashRequest(
    app_dir: PathLike,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    probe_serial: str | None = None,
    jobs: int = 8,
    *,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
    target: str | None = None,
) -> None
```

`dataclass`

Request parameters for flashing an app.

Source: `src/neuralspotx/api/_requests.py:131`

### neuralspotx.api.AppFlashRequest.target

`attribute` · `python`

```python
target: str | None = field(default=None, kw_only=True)
```

Source: `src/neuralspotx/api/_requests.py:135`

### neuralspotx.api.AppFlashRequest.jobs

`attribute` · `python`

```python
jobs: int = 8
```

Source: `src/neuralspotx/api/_requests.py:136`

## neuralspotx.api.build_app

`function` · `python`

```python
build_app(
    app_dir: PathLike | AppBuildRequest,
    *,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    target: str | None = None,
    jobs: int = 8,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
    emit: Emitter | None = None,
    on_line: Callable[[str], None] | None = None,
) -> None
```

Build an NSX app.

*timeout_s* sets a wall-clock budget for each underlying
``cmake`` / ``ninja`` subprocess; the whole process group is killed
on timeout.

*frozen* verifies ``modules/`` against ``nsx.lock`` and raises on any
drift instead of silently re-vendoring, when a (re)configure is
triggered (no ``build.ninja`` yet) — see :class:`AppActionRequest`.

Source: `src/neuralspotx/api/_app.py:135`

## neuralspotx.api.AppCleanRequest

`class` · `python`

```python
AppCleanRequest(
    app_dir: PathLike,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    probe_serial: str | None = None,
    full: bool = False,
    reset: bool = False,
    force: bool = False,
    *,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
) -> None
```

`dataclass`

Request parameters for cleaning an app build.

Source: `src/neuralspotx/api/_requests.py:139`

### neuralspotx.api.AppCleanRequest.full

`attribute` · `python`

```python
full: bool = False
```

Source: `src/neuralspotx/api/_requests.py:143`

### neuralspotx.api.AppCleanRequest.reset

`attribute` · `python`

```python
reset: bool = False
```

Source: `src/neuralspotx/api/_requests.py:144`

### neuralspotx.api.AppCleanRequest.force

`attribute` · `python`

```python
force: bool = False
```

Source: `src/neuralspotx/api/_requests.py:145`

## neuralspotx.api.AppLockRequest

`class` · `python`

```python
AppLockRequest(
    app_dir: PathLike,
    update: bool = False,
    modules: list[str] | None = None,
    check: bool = False,
    quiet: bool = False,
    timeout_s: float | None = None,
    resolve_ttl_s: float | None = None,
) -> None
```

`dataclass`

Request parameters for resolving and writing ``nsx.lock``.

Source: `src/neuralspotx/api/_requests.py:148`

### neuralspotx.api.AppLockRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

App directory containing ``nsx.yml``.

Source: `src/neuralspotx/api/_requests.py:164`

### neuralspotx.api.AppLockRequest.update

`attribute` · `python`

```python
update: bool = False
```

Re-resolve module constraints to current upstream HEAD/tag.

Source: `src/neuralspotx/api/_requests.py:165`

### neuralspotx.api.AppLockRequest.modules

`attribute` · `python`

```python
modules: list[str] | None = None
```

When given alongside ``update``, only re-resolve these.

Source: `src/neuralspotx/api/_requests.py:166`

### neuralspotx.api.AppLockRequest.check

`attribute` · `python`

```python
check: bool = False
```

Read-only mode — fail if ``nsx.lock`` would change.

Source: `src/neuralspotx/api/_requests.py:167`

### neuralspotx.api.AppLockRequest.quiet

`attribute` · `python`

```python
quiet: bool = False
```

Suppress the post-write summary print.

Source: `src/neuralspotx/api/_requests.py:168`

### neuralspotx.api.AppLockRequest.timeout_s

`attribute` · `python`

```python
timeout_s: float | None = None
```

Per-subprocess wall-clock budget (seconds).

Source: `src/neuralspotx/api/_requests.py:169`

### neuralspotx.api.AppLockRequest.resolve_ttl_s

`attribute` · `python`

```python
resolve_ttl_s: float | None = None
```

Override the resolve-ref cache TTL for this call.
``None`` uses the ``NSX_RESOLVE_TTL`` env var (default 300s).
``0`` disables caching.

Source: `src/neuralspotx/api/_requests.py:170`

## neuralspotx.api.init_module

`function` · `python`

```python
init_module(
    module_dir: PathLike | ModuleInitRequest,
    *,
    module_name: str | None = None,
    module_type: str = 'runtime',
    summary: str | None = None,
    version: str = '0.1.0',
    dependencies: list[str] | None = None,
    boards: list[str] | None = None,
    socs: list[str] | None = None,
    toolchains: list[str] | None = None,
    force: bool = False,
) -> ModuleChange
```

Create a standard custom-module skeleton on disk.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| module_dir | PathLike \| ModuleInitRequest | Required | Destination directory or a fully populated request object. When a request object is supplied, the remaining keyword arguments are ignored. |
| module_name | str \| None | None | Manifest module name. Defaults to the destination directory name. |
| module_type | str | 'runtime' | NSX module type written to ``nsx-module.yaml``. |
| summary | str \| None | None | Human-readable module summary. A placeholder is generated when omitted. |
| version | str | '0.1.0' | Initial semantic version written to the module metadata. |
| dependencies | list[str] \| None | None | Required NSX module names, in declaration order. |
| boards | list[str] \| None | None | Compatible board names. Defaults to all boards. |
| socs | list[str] \| None | None | Compatible SoC names. Defaults to all SoCs. |
| toolchains | list[str] \| None | None | Compatible toolchain names. Defaults to the NSX default toolchain. |
| force | bool | False | Allow generation into an existing non-empty directory. |

**Returns**

| Name | Type | Description |
| --- | --- | --- |
|  | ModuleChange | A change record describing the newly generated module. |

**Raises**

| Name | Description |
| --- | --- |
| NSXModuleError | The module name is empty or the destination cannot be safely used. |
| NSXConfigError | Packaged templates are unavailable. |
| ValueError | Generated metadata is invalid. |

Source: `src/neuralspotx/api/_modules.py:159`

## neuralspotx.api.AppSyncRequest

`class` · `python`

```python
AppSyncRequest(app_dir: PathLike, frozen: bool = False, force: bool = False, timeout_s: float | None = None) -> None
```

`dataclass`

Request parameters for materialising ``modules/`` from ``nsx.lock``.

Source: `src/neuralspotx/api/_requests.py:173`

### neuralspotx.api.AppSyncRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

App directory containing ``nsx.lock``.

Source: `src/neuralspotx/api/_requests.py:189`

### neuralspotx.api.AppSyncRequest.frozen

`attribute` · `python`

```python
frozen: bool = False
```

Never modify a vendored tree — verify content hashes and
fail on drift. Modules missing from disk are still fetched
(over the network for git modules) at their locked revision
and must match the lock exactly.

Source: `src/neuralspotx/api/_requests.py:190`

### neuralspotx.api.AppSyncRequest.force

`attribute` · `python`

```python
force: bool = False
```

Re-vendor every module even if content_hash matches.

Source: `src/neuralspotx/api/_requests.py:191`

### neuralspotx.api.AppSyncRequest.timeout_s

`attribute` · `python`

```python
timeout_s: float | None = None
```

Per-subprocess wall-clock budget (seconds).  Applied
to every individual ``git clone`` / ``git fetch`` invoked
during the sync.

Source: `src/neuralspotx/api/_requests.py:192`

## neuralspotx.api.flash_app

`function` · `python`

```python
flash_app(
    app_dir: PathLike | AppFlashRequest,
    *,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    target: str | None = None,
    probe_serial: str | None = None,
    jobs: int = 8,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    timeout_s: float | None = None,
    emit: Emitter | None = None,
    on_line: Callable[[str], None] | None = None,
) -> FlashResult
```

Build and flash an NSX app.

*timeout_s* sets a wall-clock budget for each underlying ``cmake``
invocation (including the J-Link flash target); the whole process
group is killed on timeout so a hung ``JLinkExe`` cannot leak.

*frozen* verifies ``modules/`` against ``nsx.lock`` and raises on any
drift instead of silently re-vendoring, when a (re)configure is
triggered — see :class:`AppActionRequest` and
:func:`neuralspotx.operations.flash_app_impl` for why passing
*probe_serial* always forces a reconfigure regardless of *frozen*.

Source: `src/neuralspotx/api/_app.py:189`

## neuralspotx.api.AppOutdatedRequest

`class` · `python`

```python
AppOutdatedRequest(app_dir: PathLike, timeout_s: float | None = None) -> None
```

`dataclass`

Request parameters for the ``nsx outdated`` report.

Source: `src/neuralspotx/api/_requests.py:195`

### neuralspotx.api.AppOutdatedRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

App directory containing ``nsx.lock``.

Source: `src/neuralspotx/api/_requests.py:206`

### neuralspotx.api.AppOutdatedRequest.timeout_s

`attribute` · `python`

```python
timeout_s: float | None = None
```

Per-subprocess wall-clock budget (seconds). Applied
to each ``git ls-remote`` invoked while comparing locked
commits to upstream tips. ``None`` disables the timeout.

Source: `src/neuralspotx/api/_requests.py:207`

## neuralspotx.api.AppUpdateRequest

`class` · `python`

```python
AppUpdateRequest(app_dir: PathLike, modules: list[str] | None = None, timeout_s: float | None = None) -> None
```

`dataclass`

Request parameters for ``nsx update`` (lock --update + sync).

Source: `src/neuralspotx/api/_requests.py:210`

### neuralspotx.api.AppUpdateRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

App directory containing ``nsx.yml``.

Source: `src/neuralspotx/api/_requests.py:222`

### neuralspotx.api.AppUpdateRequest.modules

`attribute` · `python`

```python
modules: list[str] | None = None
```

Optional list of module names to update; ``None`` means all.

Source: `src/neuralspotx/api/_requests.py:223`

### neuralspotx.api.AppUpdateRequest.timeout_s

`attribute` · `python`

```python
timeout_s: float | None = None
```

Per-subprocess wall-clock budget (seconds).  Applied
to every individual ``git`` subprocess invoked during the
re-resolve and re-vendor phases.

Source: `src/neuralspotx/api/_requests.py:224`

## neuralspotx.api.validate_module_metadata

`function` · `python`

```python
validate_module_metadata(metadata: PathLike) -> dict[str, Any]
```

Validate an ``nsx-module.yaml`` file and return the parsed data.

Raises ``NSXError`` when the file is missing, malformed, or fails
required-field checks.

Source: `src/neuralspotx/api/_modules.py:215`

## neuralspotx.api.ModuleChangeRequest

`class` · `python`

```python
ModuleChangeRequest(
    app_dir: PathLike,
    module: str,
    dry_run: bool = False,
    local: bool = False,
    vendored: bool = False,
    path: str | None = None,
    boards: tuple[str, ...] = (),
) -> None
```

`dataclass`

Request parameters for adding or removing a module.

Source: `src/neuralspotx/api/_requests.py:227`

### neuralspotx.api.ModuleChangeRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

Source: `src/neuralspotx/api/_requests.py:231`

### neuralspotx.api.ModuleChangeRequest.module

`attribute` · `python`

```python
module: str
```

Source: `src/neuralspotx/api/_requests.py:232`

### neuralspotx.api.ModuleChangeRequest.dry_run

`attribute` · `python`

```python
dry_run: bool = False
```

Source: `src/neuralspotx/api/_requests.py:233`

### neuralspotx.api.ModuleChangeRequest.local

`attribute` · `python`

```python
local: bool = False
```

Source: `src/neuralspotx/api/_requests.py:234`

### neuralspotx.api.ModuleChangeRequest.vendored

`attribute` · `python`

```python
vendored: bool = False
```

Source: `src/neuralspotx/api/_requests.py:235`

### neuralspotx.api.ModuleChangeRequest.path

`attribute` · `python`

```python
path: str | None = None
```

Source: `src/neuralspotx/api/_requests.py:236`

### neuralspotx.api.ModuleChangeRequest.boards

`attribute` · `python`

```python
boards: tuple[str, ...] = ()
```

Source: `src/neuralspotx/api/_requests.py:237`

## neuralspotx.api.find_app_root

`function` · `python`

```python
find_app_root(start: PathLike | None = None) -> Path | None
```

Find the nearest app root containing ``nsx.yml``.

Source: `src/neuralspotx/api/_modules.py:235`

## neuralspotx.api.ModuleUpdateRequest

`class` · `python`

```python
ModuleUpdateRequest(app_dir: PathLike, module: str | None = None, dry_run: bool = False) -> None
```

`dataclass`

Request parameters for updating one or more modules.

Source: `src/neuralspotx/api/_requests.py:240`

### neuralspotx.api.ModuleUpdateRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

Source: `src/neuralspotx/api/_requests.py:244`

### neuralspotx.api.ModuleUpdateRequest.module

`attribute` · `python`

```python
module: str | None = None
```

Source: `src/neuralspotx/api/_requests.py:245`

### neuralspotx.api.ModuleUpdateRequest.dry_run

`attribute` · `python`

```python
dry_run: bool = False
```

Source: `src/neuralspotx/api/_requests.py:246`

## neuralspotx.api.resolve_app_dir

`function` · `python`

```python
resolve_app_dir(explicit: PathLike | None) -> Path
```

Resolve an app directory from an explicit path or upward search.

Source: `src/neuralspotx/api/_modules.py:243`

## neuralspotx.api.reset_target

`function` · `python`

```python
reset_target(
    *,
    device: str,
    probe_serial: str | None = None,
    kind: Literal['debug', 'swpoi'] = 'debug',
    interface: str = 'SWD',
    speed_khz: int = 4000,
    timeout_s: float | None = None,
    verify_reconnect: bool = False,
    emit: Emitter | None = None,
) -> ResetResult
```

Perform an explicit J-Link reset without changing flash policy.

``swpoi`` writes ``0x1B`` to Ambiq RSTGEN at ``0x40000004``. The
resulting target disconnect is accepted only when J-Link output contains
the expected interrupted-write signature. ``verify_reconnect`` performs
a separate bounded connection after either reset kind.

Source: `src/neuralspotx/api/_app.py:248`

## neuralspotx.api.ModuleRegisterRequest

`class` · `python`

```python
ModuleRegisterRequest(
    app_dir: PathLike,
    module: str,
    metadata: PathLike,
    project: str,
    project_url: str | None = None,
    project_revision: str | None = None,
    project_path: str | None = None,
    project_local_path: PathLike | None = None,
    override: bool = False,
    dry_run: bool = False,
) -> None
```

`dataclass`

Request parameters for registering an app-local module override.

Source: `src/neuralspotx/api/_requests.py:249`

### neuralspotx.api.ModuleRegisterRequest.app_dir

`attribute` · `python`

```python
app_dir: PathLike
```

Source: `src/neuralspotx/api/_requests.py:253`

### neuralspotx.api.ModuleRegisterRequest.module

`attribute` · `python`

```python
module: str
```

Source: `src/neuralspotx/api/_requests.py:254`

### neuralspotx.api.ModuleRegisterRequest.metadata

`attribute` · `python`

```python
metadata: PathLike
```

Source: `src/neuralspotx/api/_requests.py:255`

### neuralspotx.api.ModuleRegisterRequest.project

`attribute` · `python`

```python
project: str
```

Source: `src/neuralspotx/api/_requests.py:256`

### neuralspotx.api.ModuleRegisterRequest.project_url

`attribute` · `python`

```python
project_url: str | None = None
```

Source: `src/neuralspotx/api/_requests.py:257`

### neuralspotx.api.ModuleRegisterRequest.project_revision

`attribute` · `python`

```python
project_revision: str | None = None
```

Source: `src/neuralspotx/api/_requests.py:258`

### neuralspotx.api.ModuleRegisterRequest.project_path

`attribute` · `python`

```python
project_path: str | None = None
```

Source: `src/neuralspotx/api/_requests.py:259`

### neuralspotx.api.ModuleRegisterRequest.project_local_path

`attribute` · `python`

```python
project_local_path: PathLike | None = None
```

Source: `src/neuralspotx/api/_requests.py:260`

### neuralspotx.api.ModuleRegisterRequest.override

`attribute` · `python`

```python
override: bool = False
```

Source: `src/neuralspotx/api/_requests.py:261`

### neuralspotx.api.ModuleRegisterRequest.dry_run

`attribute` · `python`

```python
dry_run: bool = False
```

Source: `src/neuralspotx/api/_requests.py:262`

## neuralspotx.api.list_modules

`function` · `python`

```python
list_modules(
    *,
    app_dir: PathLike | None = None,
    registry_only: bool = False,
    include_metadata: bool = False,
) -> list[DiscoveryRecord]
```

List available modules from the effective registry context.

By default returns lightweight records without parsing each module's
``nsx-module.yaml`` (cheap directory listing). Pass
``include_metadata=True`` for the full record set used by
``nsx module list --json`` / ``nsx module describe``.

Source: `src/neuralspotx/api/_modules.py:249`

## neuralspotx.api.describe_module

`function` · `python`

```python
describe_module(module: str, *, app_dir: PathLike | None = None) -> DiscoveryRecord
```

Describe a single module from the effective registry context.

Source: `src/neuralspotx/api/_modules.py:270`

## neuralspotx.api.view_app

`function` · `python`

```python
view_app(
    app_dir: PathLike | AppViewRequest,
    *,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    probe_serial: str | None = None,
    sdk_root: PathLike | None = None,
    frozen: bool = False,
    reset_on_open: bool | None = None,
    reset_delay_ms: int = 400,
    duration_s: float | None = None,
    capture: PathLike | None = None,
    timeout_s: float | None = None,
    emit: Emitter | None = None,
) -> None
```

Launch the SEGGER SWO viewer for an app.

*frozen* verifies ``modules/`` against ``nsx.lock`` and raises on any
drift instead of silently re-vendoring, when a (re)configure is
triggered (same trigger rule as :func:`flash_app`) — see
:class:`AppActionRequest`.

Source: `src/neuralspotx/api/_app.py:278`

## neuralspotx.api.search_modules

`function` · `python`

```python
search_modules(
    query: str,
    *,
    app_dir: PathLike | None = None,
    board: str | None = None,
    soc: str | None = None,
    toolchain: str | None = None,
    include_incompatible: bool = False,
) -> list[SearchResult]
```

Search modules by keyword and target compatibility context.

Source: `src/neuralspotx/api/_modules.py:283`

## neuralspotx.api.clean_app

`function` · `python`

```python
clean_app(
    app_dir: PathLike | AppCleanRequest,
    *,
    board: str | None = None,
    build_dir: PathLike | None = None,
    toolchain: str | None = None,
    full: bool = False,
    reset: bool = False,
    force: bool = False,
    timeout_s: float | None = None,
    emit: Emitter | None = None,
) -> None
```

Clean or fully remove an app build directory.

*timeout_s* sets a wall-clock budget for the underlying ``cmake``
clean subprocess; the whole process group is killed on timeout.

Source: `src/neuralspotx/api/_app.py:336`

---

# neuralspotx.models

Typed internal models for NSX registry, manifest, and app metadata.

This module is a thin facade: every name below is re-exported from a
sibling submodule under :mod:`neuralspotx.models`. Importers using the
historic ``from neuralspotx.models import X`` path continue to work
unchanged. New code may import from the leaf submodules directly.

## neuralspotx.models.CacheEntry

`class` · `python`

```python
CacheEntry(digest: str, path: str, size_bytes: int) -> None
```

`dataclass`

A single entry in the NSX module artifact cache.

Source: `src/neuralspotx/models/_cache.py:9`

### neuralspotx.models.CacheEntry.digest

`attribute` · `python`

```python
digest: str
```

Source: `src/neuralspotx/models/_cache.py:13`

### neuralspotx.models.CacheEntry.path

`attribute` · `python`

```python
path: str
```

Source: `src/neuralspotx/models/_cache.py:14`

### neuralspotx.models.CacheEntry.size_bytes

`attribute` · `python`

```python
size_bytes: int
```

Source: `src/neuralspotx/models/_cache.py:15`

### neuralspotx.models.CacheEntry.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_cache.py:17`

## neuralspotx.models.FlashResult

`class` · `python`

```python
FlashResult(target: str, artifact: Path, recipe: Path, probe_serial: str | None, programming_verified: bool) -> None
```

`dataclass`

Outcome of flashing one executable from an NSX app.

``programming_verified`` records that J-Link confirmed the target holds
the loaded image -- bytes freshly programmed, or programming skipped
because the contents already matched. It does not mean bytes moved.

Source: `src/neuralspotx/models/_hardware.py:10`

### neuralspotx.models.FlashResult.target

`attribute` · `python`

```python
target: str
```

Source: `src/neuralspotx/models/_hardware.py:19`

### neuralspotx.models.FlashResult.artifact

`attribute` · `python`

```python
artifact: Path
```

Source: `src/neuralspotx/models/_hardware.py:20`

### neuralspotx.models.FlashResult.recipe

`attribute` · `python`

```python
recipe: Path
```

Source: `src/neuralspotx/models/_hardware.py:21`

### neuralspotx.models.FlashResult.probe_serial

`attribute` · `python`

```python
probe_serial: str | None
```

Source: `src/neuralspotx/models/_hardware.py:22`

### neuralspotx.models.FlashResult.programming_verified

`attribute` · `python`

```python
programming_verified: bool
```

Source: `src/neuralspotx/models/_hardware.py:23`

## neuralspotx.models.OutdatedModule

`class` · `python`

```python
OutdatedModule(name: str, constraint: str, locked: str, upstream: str, status: str, url: str = '') -> None
```

`dataclass`

One git-hosted module's drift between locked commit and upstream tip.

*status* is a ``str``-mixed enum value (``OutdatedStatus``) so plain
string comparisons against ``"up-to-date"`` / ``"outdated"`` keep
working for embedders that don't import the enum.

Source: `src/neuralspotx/models/_outdated.py:13`

### neuralspotx.models.OutdatedModule.name

`attribute` · `python`

```python
name: str
```

Source: `src/neuralspotx/models/_outdated.py:22`

### neuralspotx.models.OutdatedModule.constraint

`attribute` · `python`

```python
constraint: str
```

Source: `src/neuralspotx/models/_outdated.py:23`

### neuralspotx.models.OutdatedModule.locked

`attribute` · `python`

```python
locked: str
```

Source: `src/neuralspotx/models/_outdated.py:24`

### neuralspotx.models.OutdatedModule.upstream

`attribute` · `python`

```python
upstream: str
```

Source: `src/neuralspotx/models/_outdated.py:25`

### neuralspotx.models.OutdatedModule.status

`attribute` · `python`

```python
status: str
```

Source: `src/neuralspotx/models/_outdated.py:26`

### neuralspotx.models.OutdatedModule.url

`attribute` · `python`

```python
url: str = ''
```

Source: `src/neuralspotx/models/_outdated.py:27`

### neuralspotx.models.OutdatedModule.is_outdated

`attribute` · `python`

```python
is_outdated: bool
```

Source: `src/neuralspotx/models/_outdated.py:30`

### neuralspotx.models.OutdatedModule.to_dict

`method` · `python`

```python
to_dict() -> dict[str, str]
```

Source: `src/neuralspotx/models/_outdated.py:33`

## neuralspotx.models.CommandCategory

`class` · `python`

```python
CommandCategory()
```

Category tag for CLI command graph hints.

Source: `src/neuralspotx/models/_command.py:14`

### neuralspotx.models.CommandCategory.ENTRYPOINT

`constant` · `python`

```python
ENTRYPOINT = 'entrypoint'
```

Source: `src/neuralspotx/models/_command.py:17`

### neuralspotx.models.CommandCategory.DISCOVERY

`constant` · `python`

```python
DISCOVERY = 'discovery'
```

Source: `src/neuralspotx/models/_command.py:18`

### neuralspotx.models.CommandCategory.APP_CREATION

`constant` · `python`

```python
APP_CREATION = 'app-creation'
```

Source: `src/neuralspotx/models/_command.py:19`

### neuralspotx.models.CommandCategory.DIAGNOSTICS

`constant` · `python`

```python
DIAGNOSTICS = 'diagnostics'
```

Source: `src/neuralspotx/models/_command.py:20`

### neuralspotx.models.CommandCategory.BUILD

`constant` · `python`

```python
BUILD = 'build'
```

Source: `src/neuralspotx/models/_command.py:21`

### neuralspotx.models.CommandCategory.DEPLOY

`constant` · `python`

```python
DEPLOY = 'deploy'
```

Source: `src/neuralspotx/models/_command.py:22`

### neuralspotx.models.CommandCategory.MODULES

`constant` · `python`

```python
MODULES = 'modules'
```

Source: `src/neuralspotx/models/_command.py:23`

### neuralspotx.models.CommandCategory.MAINTENANCE

`constant` · `python`

```python
MAINTENANCE = 'maintenance'
```

Source: `src/neuralspotx/models/_command.py:24`

## neuralspotx.models.ModuleChange

`class` · `python`

```python
ModuleChange(name: str, before: str | None, after: str | None, action: str, dry_run: bool = False) -> None
```

`dataclass`

One state-change applied to a module by an api.* mutation.

Source: `src/neuralspotx/models/_changes.py:14`

### neuralspotx.models.ModuleChange.name

`attribute` · `python`

```python
name: str
```

Module name.

Source: `src/neuralspotx/models/_changes.py:36`

### neuralspotx.models.ModuleChange.before

`attribute` · `python`

```python
before: str | None
```

The recorded revision (or ``None`` when the module did
not exist beforehand). May be ``None`` for ``init_module``
since there is no app-side state.

Source: `src/neuralspotx/models/_changes.py:37`

### neuralspotx.models.ModuleChange.after

`attribute` · `python`

```python
after: str | None
```

The resolved revision after the operation (or ``None``
when the module was removed).

Source: `src/neuralspotx/models/_changes.py:38`

### neuralspotx.models.ModuleChange.action

`attribute` · `python`

```python
action: str
```

One of ``"added"``, ``"removed"``, ``"updated"``,
``"noop"``. ``"added"`` covers ``add_module``/
``register_module``/``init_module`` and any transitive
dependencies pulled in. ``"removed"`` covers cascaded
removals. ``"updated"`` is recorded by ``update_modules``
when the resolved revision changed; ``"noop"`` when it did
not.

Source: `src/neuralspotx/models/_changes.py:39`

### neuralspotx.models.ModuleChange.dry_run

`attribute` · `python`

```python
dry_run: bool = False
```

``True`` when the change was predicted by a
``dry_run=True`` call and not actually applied.

Source: `src/neuralspotx/models/_changes.py:40`

### neuralspotx.models.ModuleChange.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_changes.py:42`

## neuralspotx.models.SearchMatch

`class` · `python`

```python
SearchMatch(field: str, term: str, value: str) -> None
```

`dataclass`

A single field match from module search scoring.

Source: `src/neuralspotx/models/_discovery.py:14`

### neuralspotx.models.SearchMatch.field

`attribute` · `python`

```python
field: str
```

Source: `src/neuralspotx/models/_discovery.py:18`

### neuralspotx.models.SearchMatch.term

`attribute` · `python`

```python
term: str
```

Source: `src/neuralspotx/models/_discovery.py:19`

### neuralspotx.models.SearchMatch.value

`attribute` · `python`

```python
value: str
```

Source: `src/neuralspotx/models/_discovery.py:20`

### neuralspotx.models.SearchMatch.to_dict

`method` · `python`

```python
to_dict() -> dict[str, str]
```

Source: `src/neuralspotx/models/_discovery.py:22`

## neuralspotx.models.CacheInfo

`class` · `python`

```python
CacheInfo(root: str, disabled: bool, entries: tuple[CacheEntry, ...]) -> None
```

`dataclass`

Snapshot of the NSX module artifact cache.

Source: `src/neuralspotx/models/_cache.py:21`

### neuralspotx.models.CacheInfo.root

`attribute` · `python`

```python
root: str
```

Source: `src/neuralspotx/models/_cache.py:25`

### neuralspotx.models.CacheInfo.disabled

`attribute` · `python`

```python
disabled: bool
```

Source: `src/neuralspotx/models/_cache.py:26`

### neuralspotx.models.CacheInfo.entries

`attribute` · `python`

```python
entries: tuple[CacheEntry, ...]
```

Source: `src/neuralspotx/models/_cache.py:27`

### neuralspotx.models.CacheInfo.entry_count

`attribute` · `python`

```python
entry_count: int
```

Source: `src/neuralspotx/models/_cache.py:30`

### neuralspotx.models.CacheInfo.total_size_bytes

`attribute` · `python`

```python
total_size_bytes: int
```

Source: `src/neuralspotx/models/_cache.py:34`

### neuralspotx.models.CacheInfo.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_cache.py:37`

## neuralspotx.models.ResetResult

`class` · `python`

```python
ResetResult(
    device: str,
    kind: Literal['debug', 'swpoi'],
    probe_serial: str | None,
    interface: str,
    speed_khz: int,
    expected_disconnect: bool,
    reconnect_verified: bool | None,
) -> None
```

`dataclass`

Outcome of an explicit J-Link reset operation.

Source: `src/neuralspotx/models/_hardware.py:26`

### neuralspotx.models.ResetResult.device

`attribute` · `python`

```python
device: str
```

Source: `src/neuralspotx/models/_hardware.py:30`

### neuralspotx.models.ResetResult.kind

`attribute` · `python`

```python
kind: Literal['debug', 'swpoi']
```

Source: `src/neuralspotx/models/_hardware.py:31`

### neuralspotx.models.ResetResult.probe_serial

`attribute` · `python`

```python
probe_serial: str | None
```

Source: `src/neuralspotx/models/_hardware.py:32`

### neuralspotx.models.ResetResult.interface

`attribute` · `python`

```python
interface: str
```

Source: `src/neuralspotx/models/_hardware.py:33`

### neuralspotx.models.ResetResult.speed_khz

`attribute` · `python`

```python
speed_khz: int
```

Source: `src/neuralspotx/models/_hardware.py:34`

### neuralspotx.models.ResetResult.expected_disconnect

`attribute` · `python`

```python
expected_disconnect: bool
```

Source: `src/neuralspotx/models/_hardware.py:35`

### neuralspotx.models.ResetResult.reconnect_verified

`attribute` · `python`

```python
reconnect_verified: bool | None
```

Source: `src/neuralspotx/models/_hardware.py:36`

## neuralspotx.models.CommandScope

`class` · `python`

```python
CommandScope()
```

Scope tag for CLI command graph hints.

Source: `src/neuralspotx/models/_command.py:27`

### neuralspotx.models.CommandScope.GLOBAL

`constant` · `python`

```python
GLOBAL = 'global'
```

Source: `src/neuralspotx/models/_command.py:30`

### neuralspotx.models.CommandScope.APP

`constant` · `python`

```python
APP = 'app'
```

Source: `src/neuralspotx/models/_command.py:31`

### neuralspotx.models.CommandScope.ENVIRONMENT

`constant` · `python`

```python
ENVIRONMENT = 'environment'
```

Source: `src/neuralspotx/models/_command.py:32`

### neuralspotx.models.CommandScope.FILESYSTEM

`constant` · `python`

```python
FILESYSTEM = 'filesystem'
```

Source: `src/neuralspotx/models/_command.py:33`

## neuralspotx.models.CommandHint

`class` · `python`

```python
CommandHint(
    category: CommandCategory,
    scope: CommandScope,
    next_commands: tuple[str, ...] = (),
    alias_for: str | None = None,
) -> None
```

`dataclass`

Typed metadata hint for a CLI command in the command graph.

Source: `src/neuralspotx/models/_command.py:36`

### neuralspotx.models.CommandHint.category

`attribute` · `python`

```python
category: CommandCategory
```

Source: `src/neuralspotx/models/_command.py:40`

### neuralspotx.models.CommandHint.scope

`attribute` · `python`

```python
scope: CommandScope
```

Source: `src/neuralspotx/models/_command.py:41`

### neuralspotx.models.CommandHint.next_commands

`attribute` · `python`

```python
next_commands: tuple[str, ...] = ()
```

Source: `src/neuralspotx/models/_command.py:42`

### neuralspotx.models.CommandHint.alias_for

`attribute` · `python`

```python
alias_for: str | None = None
```

Source: `src/neuralspotx/models/_command.py:43`

### neuralspotx.models.CommandHint.to_dict

`method` · `python`

```python
to_dict() -> dict[str, str | list[str]]
```

Source: `src/neuralspotx/models/_command.py:45`

## neuralspotx.models.DiscoveryRecord

`class` · `python`

```python
DiscoveryRecord(
    name: str,
    project: str,
    revision: str,
    metadata: str | None,
    enabled: bool,
    metadata_available: bool = False,
    metadata_error: str | None = None,
    module: dict[str, Any] | None = None,
    support: dict[str, Any] | None = None,
    build: dict[str, Any] | None = None,
    depends: dict[str, Any] | None = None,
    compatibility: dict[str, Any] | None = None,
    summary: str | None = None,
    capabilities: list[str] | None = None,
    use_cases: list[str] | None = None,
    anti_use_cases: list[str] | None = None,
    agent_keywords: list[str] | None = None,
    example_refs: list[Any] | None = None,
    composition_hints: dict[str, Any] | None = None,
    provides: dict[str, Any] | None = None,
    constraints: dict[str, Any] | None = None,
    integrations: dict[str, Any] | None = None,
) -> None
```

`dataclass`

Typed module discovery record returned by list/describe/search APIs.

Source: `src/neuralspotx/models/_discovery.py:41`

### neuralspotx.models.DiscoveryRecord.name

`attribute` · `python`

```python
name: str
```

Source: `src/neuralspotx/models/_discovery.py:46`

### neuralspotx.models.DiscoveryRecord.project

`attribute` · `python`

```python
project: str
```

Source: `src/neuralspotx/models/_discovery.py:47`

### neuralspotx.models.DiscoveryRecord.revision

`attribute` · `python`

```python
revision: str
```

Source: `src/neuralspotx/models/_discovery.py:48`

### neuralspotx.models.DiscoveryRecord.metadata

`attribute` · `python`

```python
metadata: str | None
```

Source: `src/neuralspotx/models/_discovery.py:49`

### neuralspotx.models.DiscoveryRecord.enabled

`attribute` · `python`

```python
enabled: bool
```

Source: `src/neuralspotx/models/_discovery.py:50`

### neuralspotx.models.DiscoveryRecord.metadata_available

`attribute` · `python`

```python
metadata_available: bool = False
```

Source: `src/neuralspotx/models/_discovery.py:53`

### neuralspotx.models.DiscoveryRecord.metadata_error

`attribute` · `python`

```python
metadata_error: str | None = None
```

Source: `src/neuralspotx/models/_discovery.py:54`

### neuralspotx.models.DiscoveryRecord.module

`attribute` · `python`

```python
module: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:57`

### neuralspotx.models.DiscoveryRecord.support

`attribute` · `python`

```python
support: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:58`

### neuralspotx.models.DiscoveryRecord.build

`attribute` · `python`

```python
build: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:59`

### neuralspotx.models.DiscoveryRecord.depends

`attribute` · `python`

```python
depends: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:60`

### neuralspotx.models.DiscoveryRecord.compatibility

`attribute` · `python`

```python
compatibility: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:61`

### neuralspotx.models.DiscoveryRecord.summary

`attribute` · `python`

```python
summary: str | None = None
```

Source: `src/neuralspotx/models/_discovery.py:64`

### neuralspotx.models.DiscoveryRecord.capabilities

`attribute` · `python`

```python
capabilities: list[str] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:65`

### neuralspotx.models.DiscoveryRecord.use_cases

`attribute` · `python`

```python
use_cases: list[str] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:66`

### neuralspotx.models.DiscoveryRecord.anti_use_cases

`attribute` · `python`

```python
anti_use_cases: list[str] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:67`

### neuralspotx.models.DiscoveryRecord.agent_keywords

`attribute` · `python`

```python
agent_keywords: list[str] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:68`

### neuralspotx.models.DiscoveryRecord.example_refs

`attribute` · `python`

```python
example_refs: list[Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:69`

### neuralspotx.models.DiscoveryRecord.composition_hints

`attribute` · `python`

```python
composition_hints: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:70`

### neuralspotx.models.DiscoveryRecord.provides

`attribute` · `python`

```python
provides: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:71`

### neuralspotx.models.DiscoveryRecord.constraints

`attribute` · `python`

```python
constraints: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:72`

### neuralspotx.models.DiscoveryRecord.integrations

`attribute` · `python`

```python
integrations: dict[str, Any] | None = None
```

Source: `src/neuralspotx/models/_discovery.py:73`

### neuralspotx.models.DiscoveryRecord.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Serialize to a dict matching the legacy discovery record format.

Source: `src/neuralspotx/models/_discovery.py:75`

## neuralspotx.models.OutdatedSkip

`class` · `python`

```python
OutdatedSkip(name: str, reason: str) -> None
```

`dataclass`

A module that ``api.outdated_app`` could not check, with a reason.

Source: `src/neuralspotx/models/_outdated.py:44`

### neuralspotx.models.OutdatedSkip.name

`attribute` · `python`

```python
name: str
```

Source: `src/neuralspotx/models/_outdated.py:48`

### neuralspotx.models.OutdatedSkip.reason

`attribute` · `python`

```python
reason: str
```

Source: `src/neuralspotx/models/_outdated.py:49`

### neuralspotx.models.OutdatedSkip.to_dict

`method` · `python`

```python
to_dict() -> dict[str, str]
```

Source: `src/neuralspotx/models/_outdated.py:51`

## neuralspotx.models.CacheCleanResult

`class` · `python`

```python
CacheCleanResult(root: str, removed_count: int, dry_run: bool = False) -> None
```

`dataclass`

Outcome of an :func:`api.clean_cache` invocation.

Source: `src/neuralspotx/models/_cache.py:47`

### neuralspotx.models.CacheCleanResult.root

`attribute` · `python`

```python
root: str
```

Source: `src/neuralspotx/models/_cache.py:51`

### neuralspotx.models.CacheCleanResult.removed_count

`attribute` · `python`

```python
removed_count: int
```

Source: `src/neuralspotx/models/_cache.py:52`

### neuralspotx.models.CacheCleanResult.dry_run

`attribute` · `python`

```python
dry_run: bool = False
```

Source: `src/neuralspotx/models/_cache.py:53`

### neuralspotx.models.CacheCleanResult.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_cache.py:55`

## neuralspotx.models.OutdatedReport

`class` · `python`

```python
OutdatedReport(checked: tuple[OutdatedModule, ...], skipped: tuple[OutdatedSkip, ...] = ()) -> None
```

`dataclass`

Aggregate result returned by ``api.outdated_app()``.

``checked`` preserves the order in which modules were inspected so
embedders can render a deterministic table; ``skipped`` records
modules that could not be resolved (no URL, ``git ls-remote``
failure, etc.). The ``outdated`` property is a convenience filter
that mirrors what the historic CLI returned as an integer count.

Source: `src/neuralspotx/models/_outdated.py:55`

### neuralspotx.models.OutdatedReport.checked

`attribute` · `python`

```python
checked: tuple[OutdatedModule, ...]
```

Source: `src/neuralspotx/models/_outdated.py:66`

### neuralspotx.models.OutdatedReport.skipped

`attribute` · `python`

```python
skipped: tuple[OutdatedSkip, ...] = ()
```

Source: `src/neuralspotx/models/_outdated.py:67`

### neuralspotx.models.OutdatedReport.outdated

`attribute` · `python`

```python
outdated: tuple[OutdatedModule, ...]
```

Source: `src/neuralspotx/models/_outdated.py:70`

### neuralspotx.models.OutdatedReport.outdated_count

`attribute` · `python`

```python
outdated_count: int
```

Source: `src/neuralspotx/models/_outdated.py:74`

### neuralspotx.models.OutdatedReport.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_outdated.py:77`

## neuralspotx.models.DoctorCheck

`class` · `python`

```python
DoctorCheck(label: str, ok: bool, required: bool = True, detail: str | None = None, hint: str | None = None) -> None
```

`dataclass`

One environment / toolchain check produced by ``api.doctor()``.

*required* discriminates checks that gate ``ok`` (e.g. ``cmake``)
from informational ones (e.g. ATfE when ``ATFE_ROOT`` is set, or
individual armclang components when the toolchain was detected).

Source: `src/neuralspotx/models/_command.py:56`

### neuralspotx.models.DoctorCheck.label

`attribute` · `python`

```python
label: str
```

Source: `src/neuralspotx/models/_command.py:65`

### neuralspotx.models.DoctorCheck.ok

`attribute` · `python`

```python
ok: bool
```

Source: `src/neuralspotx/models/_command.py:66`

### neuralspotx.models.DoctorCheck.required

`attribute` · `python`

```python
required: bool = True
```

Source: `src/neuralspotx/models/_command.py:67`

### neuralspotx.models.DoctorCheck.detail

`attribute` · `python`

```python
detail: str | None = None
```

Source: `src/neuralspotx/models/_command.py:68`

### neuralspotx.models.DoctorCheck.hint

`attribute` · `python`

```python
hint: str | None = None
```

Source: `src/neuralspotx/models/_command.py:69`

### neuralspotx.models.DoctorCheck.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_command.py:71`

## neuralspotx.models.DoctorReport

`class` · `python`

```python
DoctorReport(checks: tuple[DoctorCheck, ...], notes: tuple[str, ...] = ()) -> None
```

`dataclass`

Aggregate result returned by ``api.doctor()``.

``ok`` is ``True`` iff every *required* check passed.
``checks`` preserves the order in which checks ran so embedders can
render a deterministic table. ``notes`` carries free-form lines
(e.g. "ATfE toolchain not detected — optional") for parity with the
historic CLI output.

Source: `src/neuralspotx/models/_command.py:81`

### neuralspotx.models.DoctorReport.checks

`attribute` · `python`

```python
checks: tuple[DoctorCheck, ...]
```

Source: `src/neuralspotx/models/_command.py:92`

### neuralspotx.models.DoctorReport.notes

`attribute` · `python`

```python
notes: tuple[str, ...] = ()
```

Source: `src/neuralspotx/models/_command.py:93`

### neuralspotx.models.DoctorReport.ok

`attribute` · `python`

```python
ok: bool
```

Source: `src/neuralspotx/models/_command.py:96`

### neuralspotx.models.DoctorReport.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_command.py:99`

## neuralspotx.models.SearchResult

`class` · `python`

```python
SearchResult(
    name: str,
    project: str,
    revision: str,
    metadata: str | None,
    enabled: bool,
    metadata_available: bool = False,
    metadata_error: str | None = None,
    module: dict[str, Any] | None = None,
    support: dict[str, Any] | None = None,
    build: dict[str, Any] | None = None,
    depends: dict[str, Any] | None = None,
    compatibility: dict[str, Any] | None = None,
    summary: str | None = None,
    capabilities: list[str] | None = None,
    use_cases: list[str] | None = None,
    anti_use_cases: list[str] | None = None,
    agent_keywords: list[str] | None = None,
    example_refs: list[Any] | None = None,
    composition_hints: dict[str, Any] | None = None,
    provides: dict[str, Any] | None = None,
    constraints: dict[str, Any] | None = None,
    integrations: dict[str, Any] | None = None,
    score: int = 0,
    matches: tuple[SearchMatch, ...] = (),
    compatible: bool | None = None,
) -> None
```

`dataclass`

A discovery record augmented with search scoring.

Source: `src/neuralspotx/models/_discovery.py:102`

### neuralspotx.models.SearchResult.score

`attribute` · `python`

```python
score: int = 0
```

Source: `src/neuralspotx/models/_discovery.py:106`

### neuralspotx.models.SearchResult.matches

`attribute` · `python`

```python
matches: tuple[SearchMatch, ...] = ()
```

Source: `src/neuralspotx/models/_discovery.py:107`

### neuralspotx.models.SearchResult.compatible

`attribute` · `python`

```python
compatible: bool | None = None
```

Source: `src/neuralspotx/models/_discovery.py:108`

### neuralspotx.models.SearchResult.from_record

`method` · `python`

```python
from_record(
    record: DiscoveryRecord,
    *,
    score: int,
    matches: tuple[SearchMatch, ...],
    compatible: bool | None,
) -> SearchResult
```

`classmethod`

Source: `src/neuralspotx/models/_discovery.py:110`

### neuralspotx.models.SearchResult.to_dict

`method` · `python`

```python
to_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/models/_discovery.py:122`

---

# neuralspotx.nsx_lock

nsx.lock — resolution receipt for an NSX app.

Phase 1 of the lock/sync system. Records, per app, the exact resolved
git commit and content hash of every vendored module so that builds are
reproducible and `nsx sync` can deterministically restore the modules/
tree.

Schema (YAML, v4):

```yaml
schema_version: 4
targets:
  <board>:                      # one resolution section per board
    generated_at: <ISO 8601 UTC>
    nsx_tool: { version: <pkg version> }
    manifest: { path: nsx.yml, hash: sha256:<hex> }
    target: { board, soc, toolchain }
    modules:
      <module-name>:
        project: <project-key>
        kind: git | packaged | local | vendored | unresolved
        constraint: <revision string from nsx.yml>
        resolved:
          # git only:
          url: <repo url>
          tag: <tag name>           # set when constraint resolved through a tag
          commit: <40-char SHA>     # ALWAYS the underlying commit SHA, not
                                    # the annotated-tag-object SHA
          # all kinds:
          vendored_at: <relpath under app dir>
          content_hash: sha256:<hex>
          acquired_at: <ISO 8601 UTC>
          # packaged only:
          tool_version: <neuralspotx pkg version>
```

Every app — single- or multi-target — keeps exactly one ``nsx.lock``
whose ``targets`` map holds a resolution section per board, so the app
root has one manifest (``nsx.yml``) and one lock (``nsx.lock``).

``content_hash`` semantics (v3, cargo/uv-style — hashes the *upstream
artifact*, never the on-disk vendored tree):

    git        — hash of the git working tree at the locked commit
                  (computed by cloning at ``commit`` into a tempdir,
                  stripping ``.git``, and hashing). Independent of
                  whether/how the module is currently vendored under
                  ``modules/``.
    packaged   — hash of the packaged source tree shipped inside the
                  ``neuralspotx`` Python wheel (the registry resource
                  dir).
    local      — if the registry project has a ``local_path``: hash of
                  that source directory. Otherwise (in-tree local, e.g.
                  ``nsx module add --local``): hash of
                  ``modules/<name>/`` itself — the directory IS the
                  source.
    vendored   — hash of ``modules/<name>/`` itself — the directory IS
                  the source (committed in the app).
    unresolved — last-known hash of ``modules/<name>/`` from the
                  previous lock or the current on-disk tree, since
                  upstream is unreachable.

This decoupling means ``nsx lock`` can produce real hashes on a fresh
checkout (no ``modules/`` populated yet) and ``nsx sync`` never needs
to modify the lock to keep it in sync with reality — the lock is
written exactly once per actual change to the upstream resolution.

:::note[v4 changes vs v3]
* Single combined lock file. Previously single-target apps wrote a
  flat ``nsx.lock`` and multi-target apps wrote one
  ``nsx.<board>.lock`` per board; v4 collapses both into one
  ``nsx.lock`` with a ``targets: { <board>: <section> }`` map.
  ``schema_version`` is recorded once at the document root.
* ``acquired_at`` / ``generated_at`` are preserved across re-locks
  when the resolution is unchanged, so a no-op ``nsx lock`` produces
  a byte-identical file (no timestamp-only diff churn).

:::

:::note[v3 changes vs v2]
* ``content_hash`` is now the upstream-artifact hash, not the
  materialized tree hash. Schema-wise the field is identical; the
  bump signals the semantic change so v2 lockfiles are regenerated.

:::

:::note[v2 changes vs v1]
* Drop `ref:` (was always equal to `constraint:`).
* Add `tag:` — distinct from `constraint:` so we can tell whether the
  constraint resolved via a tag (vs a branch or raw SHA).
* `commit:` is guaranteed to be the underlying commit SHA. v1 stored
  the annotated-tag-object SHA when the constraint was an annotated
  tag, which broke `git checkout` reproducibility if the tag was
  later force-moved.

:::

No back-compat reads for older schemas: pre-1.0, only one user; old
locks are rejected and the user is told to run ``nsx lock``.

Kinds (the user-facing 'source:' field in nsx.yml maps to a kind):
    git        -> registry git module (default; sync re-clones at locked SHA)
    packaged   -> shipped inside the neuralspotx package (sync re-copies)
    local      -> linked from an external path (legacy ``local: true``)
    vendored   -> source: { vendored: true }  (committed in app; sync hands-off)
    unresolved -> registry module whose upstream was unreachable at lock time
                  (content-only entry; sync verifies hash, can't re-fetch)

Public API kept intentionally small so the CLI/operations layer can
compose these primitives. The module is implemented as a package
(``nsx_lock/``) split into focused submodules; this ``__init__`` is a
facade that re-exports the historical flat API so
``from neuralspotx.nsx_lock import X`` keeps working unchanged.

## neuralspotx.nsx_lock.LockKind

`class` · `python`

```python
LockKind()
```

Resolution kind for a single lock entry.

Mixed with ``str`` so existing code that compares ``entry.kind ==
"git"`` keeps working unchanged. New code should prefer the enum
members (``LockKind.GIT``) for static checking and refactor safety.

Source: `src/neuralspotx/nsx_lock/_kinds.py:8`

### neuralspotx.nsx_lock.LockKind.GIT

`constant` · `python`

```python
GIT = 'git'
```

Source: `src/neuralspotx/nsx_lock/_kinds.py:16`

### neuralspotx.nsx_lock.LockKind.PACKAGED

`constant` · `python`

```python
PACKAGED = 'packaged'
```

Source: `src/neuralspotx/nsx_lock/_kinds.py:17`

### neuralspotx.nsx_lock.LockKind.LOCAL

`constant` · `python`

```python
LOCAL = 'local'
```

Source: `src/neuralspotx/nsx_lock/_kinds.py:18`

### neuralspotx.nsx_lock.LockKind.VENDORED

`constant` · `python`

```python
VENDORED = 'vendored'
```

Source: `src/neuralspotx/nsx_lock/_kinds.py:19`

### neuralspotx.nsx_lock.LockKind.UNRESOLVED

`constant` · `python`

```python
UNRESOLVED = 'unresolved'
```

Source: `src/neuralspotx/nsx_lock/_kinds.py:20`

## neuralspotx.nsx_lock.ResolvedModule

`class` · `python`

```python
ResolvedModule(
    project: str,
    kind: LockKind,
    constraint: str,
    vendored_at: str,
    content_hash: str,
    acquired_at: str,
    url: str | None = None,
    tag: str | None = None,
    commit: str | None = None,
    tool_version: str | None = None,
) -> None
```

`dataclass`

Resolution record for one module.

Source: `src/neuralspotx/nsx_lock/_models.py:14`

### neuralspotx.nsx_lock.ResolvedModule.project

`attribute` · `python`

```python
project: str
```

Source: `src/neuralspotx/nsx_lock/_models.py:18`

### neuralspotx.nsx_lock.ResolvedModule.kind

`attribute` · `python`

```python
kind: LockKind
```

Source: `src/neuralspotx/nsx_lock/_models.py:19`

### neuralspotx.nsx_lock.ResolvedModule.constraint

`attribute` · `python`

```python
constraint: str
```

Source: `src/neuralspotx/nsx_lock/_models.py:20`

### neuralspotx.nsx_lock.ResolvedModule.vendored_at

`attribute` · `python`

```python
vendored_at: str
```

Source: `src/neuralspotx/nsx_lock/_models.py:21`

### neuralspotx.nsx_lock.ResolvedModule.content_hash

`attribute` · `python`

```python
content_hash: str
```

Source: `src/neuralspotx/nsx_lock/_models.py:22`

### neuralspotx.nsx_lock.ResolvedModule.acquired_at

`attribute` · `python`

```python
acquired_at: str
```

Source: `src/neuralspotx/nsx_lock/_models.py:23`

### neuralspotx.nsx_lock.ResolvedModule.url

`attribute` · `python`

```python
url: str | None = None
```

Source: `src/neuralspotx/nsx_lock/_models.py:24`

### neuralspotx.nsx_lock.ResolvedModule.tag

`attribute` · `python`

```python
tag: str | None = None
```

Source: `src/neuralspotx/nsx_lock/_models.py:25`

### neuralspotx.nsx_lock.ResolvedModule.commit

`attribute` · `python`

```python
commit: str | None = None
```

Source: `src/neuralspotx/nsx_lock/_models.py:26`

### neuralspotx.nsx_lock.ResolvedModule.tool_version

`attribute` · `python`

```python
tool_version: str | None = None
```

Source: `src/neuralspotx/nsx_lock/_models.py:27`

### neuralspotx.nsx_lock.ResolvedModule.to_yaml_dict

`method` · `python`

```python
to_yaml_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/nsx_lock/_models.py:29`

### neuralspotx.nsx_lock.ResolvedModule.from_yaml_dict

`method` · `python`

```python
from_yaml_dict(name: str, data: dict[str, Any]) -> 'ResolvedModule'
```

`classmethod`

Source: `src/neuralspotx/nsx_lock/_models.py:50`

## neuralspotx.nsx_lock.NsxLock

`class` · `python`

```python
NsxLock(
    schema_version: int = LOCK_SCHEMA_VERSION,
    generated_at: str = '',
    nsx_tool_version: str | None = None,
    manifest_path: str = 'nsx.yml',
    manifest_hash: str = '',
    target: dict[str, str] = dict(),
    modules: dict[str, ResolvedModule] = dict(),
    path: Path | None = None,
) -> None
```

`dataclass`

Top-level nsx.lock document.

Source: `src/neuralspotx/nsx_lock/_models.py:74`

### neuralspotx.nsx_lock.NsxLock.schema_version

`attribute` · `python`

```python
schema_version: int = LOCK_SCHEMA_VERSION
```

Source: `src/neuralspotx/nsx_lock/_models.py:78`

### neuralspotx.nsx_lock.NsxLock.generated_at

`attribute` · `python`

```python
generated_at: str = ''
```

Source: `src/neuralspotx/nsx_lock/_models.py:79`

### neuralspotx.nsx_lock.NsxLock.nsx_tool_version

`attribute` · `python`

```python
nsx_tool_version: str | None = None
```

Source: `src/neuralspotx/nsx_lock/_models.py:80`

### neuralspotx.nsx_lock.NsxLock.manifest_path

`attribute` · `python`

```python
manifest_path: str = 'nsx.yml'
```

Source: `src/neuralspotx/nsx_lock/_models.py:81`

### neuralspotx.nsx_lock.NsxLock.manifest_hash

`attribute` · `python`

```python
manifest_hash: str = ''
```

Source: `src/neuralspotx/nsx_lock/_models.py:82`

### neuralspotx.nsx_lock.NsxLock.target

`attribute` · `python`

```python
target: dict[str, str] = field(default_factory=dict)
```

Source: `src/neuralspotx/nsx_lock/_models.py:83`

### neuralspotx.nsx_lock.NsxLock.modules

`attribute` · `python`

```python
modules: dict[str, ResolvedModule] = field(default_factory=dict)
```

Source: `src/neuralspotx/nsx_lock/_models.py:84`

### neuralspotx.nsx_lock.NsxLock.path

`attribute` · `python`

```python
path: Path | None = field(default=None, compare=False, repr=False)
```

Source: `src/neuralspotx/nsx_lock/_models.py:89`

### neuralspotx.nsx_lock.NsxLock.to_yaml_dict

`method` · `python`

```python
to_yaml_dict() -> dict[str, Any]
```

Source: `src/neuralspotx/nsx_lock/_models.py:91`

### neuralspotx.nsx_lock.NsxLock.to_section_dict

`method` · `python`

```python
to_section_dict() -> dict[str, Any]
```

Serialize as a per-board section of a combined :class:`LockFile`.

Identical to :meth:`to_yaml_dict` minus ``schema_version`` — the
schema version is hoisted to the combined document root so it is
recorded once, not once per target.

Source: `src/neuralspotx/nsx_lock/_models.py:101`

### neuralspotx.nsx_lock.NsxLock.from_yaml_dict

`method` · `python`

```python
from_yaml_dict(data: dict[str, Any]) -> 'NsxLock'
```

`classmethod`

Source: `src/neuralspotx/nsx_lock/_models.py:117`

### neuralspotx.nsx_lock.NsxLock.from_section_dict

`method` · `python`

```python
from_section_dict(data: dict[str, Any]) -> 'NsxLock'
```

`classmethod`

Parse a per-board section of a combined :class:`LockFile`.

The section carries no ``schema_version`` of its own (it is
validated once at the document root); the returned object is
stamped with the current :data:`LOCK_SCHEMA_VERSION`.

Source: `src/neuralspotx/nsx_lock/_models.py:143`

---

# neuralspotx.operations

Shared NSX workflow operations for CLI and programmatic use.

The package implements every ``*_impl`` workhorse behind
``neuralspotx.api`` and ``nsx`` (the CLI) in focused sub-modules. The
public surface is re-exported here so existing callers (``api``,
``cli``, tests) can reference ``neuralspotx.operations.<name>``
unchanged.

Sub-module layout
-----------------

* ``_common``         — verbosity context (``set_verbosity``,
                        ``get_verbosity``, ``verbosity``), status
                        enums, name helpers, build-context resolver,
                        vendored-module scaffolder.
* ``_app_lifecycle``  — ``create_app_impl``, ``init_module_impl``.
* ``_doctor``         — ``doctor_impl``.
* ``_lock``           — ``lock_app_impl``, ``outdated_app_impl`` and helpers.
* ``_sync``           — ``sync_app_impl``, ``update_app_impl``,
                        ``_ensure_app_modules``.
* ``_build``          — ``configure_app_impl``, ``build_app_impl``,
                        ``flash_app_impl``, ``view_app_impl``,
                        ``clean_app_impl``.
* ``_modules``        — ``add_module_impl``, ``remove_module_impl``,
                        ``update_modules_impl``, ``register_module_impl``.
* ``_cache``          — ``cache_info_impl``, ``clean_cache_impl``.

Tests that need to monkeypatch helpers imported by a specific sub-module
should target that sub-module directly (e.g. ``operations._lock.resolve_ref``)
rather than the package, since ``from .nsx_lock import resolve_ref`` binds
the name in the importing sub-module's globals.

## neuralspotx.operations.OutdatedStatus

`class` · `python`

```python
OutdatedStatus()
```

Per-module status emitted by ``nsx outdated``.

Mixed with ``str`` so callers comparing against the legacy
``"up-to-date"`` / ``"outdated"`` spellings keep working.

Source: `src/neuralspotx/operations/_common.py:69`

### neuralspotx.operations.OutdatedStatus.UP_TO_DATE

`constant` · `python`

```python
UP_TO_DATE = 'up-to-date'
```

Source: `src/neuralspotx/operations/_common.py:76`

### neuralspotx.operations.OutdatedStatus.OUTDATED

`constant` · `python`

```python
OUTDATED = 'outdated'
```

Source: `src/neuralspotx/operations/_common.py:77`

## neuralspotx.operations.ProfileStatus

`class` · `python`

```python
ProfileStatus()
```

Profile lifecycle marker stored in ``nsx.yml``.

``ACTIVE`` — profile is fully supported.
``SCAFFOLD`` — profile exists but build bring-up may be incomplete.

Source: `src/neuralspotx/operations/_common.py:83`

### neuralspotx.operations.ProfileStatus.ACTIVE

`constant` · `python`

```python
ACTIVE = 'active'
```

Source: `src/neuralspotx/operations/_common.py:90`

### neuralspotx.operations.ProfileStatus.SCAFFOLD

`constant` · `python`

```python
SCAFFOLD = 'scaffold'
```

Source: `src/neuralspotx/operations/_common.py:91`