Metadata-Version: 2.4
Name: hugpy-discovery
Version: 0.1.21
Summary: Independent model inventory and host-scoped engine route evidence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: abstract_database>=0.0.2.213
Requires-Dist: hugpy-resources<0.2,>=0.1.15
Requires-Dist: sentencepiece>=0.2
Requires-Dist: protobuf>=4
Requires-Dist: hugpy-settings<0.2,>=0.1.8
Requires-Dist: hugpy-terminal<0.2,>=0.1.24
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3; extra == "postgres"
Provides-Extra: downloader
Requires-Dist: hugpy-downloader>=0.1.0.2; extra == "downloader"

# Hugpy Discovery

> `pip install hugpy-discovery` runs in **user mode**: no kernel drive-change watching, state in ~/.local/share/hugpy.
> For the system service (account, units, drive relay) run `sudo hugpy-discovery system install`, or `sudo apt install hugpy-discovery` from https://hugpy.ai/apt.

Run `hugpy-discovery settings` to open the Drives, Database and Shared top tabs.
Each tab has its own table with individually selectable cells and editing in
place. The live console also keeps its Status tab (process ledger and Build now)
and a View tab: a two-pane read-only database browser with the tables on the
left (`s` orders filled tables first) and the selected table's rows on the right.
In the rows, `/` searches every column, `s` sorts by the highlighted column,
`<`/`>` move it, `+`/`-`/`w` widen, narrow or fit it, `h`/`H` hide and restore columns, Enter expands a row, and
`c`/`r`/`t` copy the cell, the row (JSON) or the table (CSV) as arranged on screen.
Wrapper settings → Discovery opens the same `hugpy-settings` editor and shared
profile on the machine running the terminal UI (including an SSH terminal).
It does not create a second settings store or a new server API.
Drive rows contain a directory, central/worker/immutable designation, Resolve
identities switch and Offline provider lookups switch. Add a drive opens the
file browser; select an existing path cell to type in place or press F2 to browse. The most specific
configured directory supplies the identity policy for a model. Saving a drive
row also updates the folder lists consumed by Wrapper.

Database contains the backend selector, editable inspector interface and port,
SQLite rows (On/Off, file size, full path), and PostgreSQL rows (On/Off, size,
host, port, database, user, masked password). Each backend has at most one enabled
row. PostgreSQL sizes are fetched with the Size / check cell;
unchecked sizes say "not checked". Connection settings do not provision a database.
Standalone Discovery inventory still requires SQLite; selecting PostgreSQL gives
an explicit unsupported-backend message. Disabling every SQLite row prevents a
new Discovery launch from silently using a different file.

Shared contains masked Hugging Face and Civitai tokens and explicitly selected
environment files. Add opens the file browser; existing files can be replaced,
typed or removed from settings. Files are parsed as assignments, never executed.
Process environment variables override the selected files (later files win),
which override saved values, followed by Resources terms defaults.

Arrows move between cells; Tab/Shift-Tab change sections. Click a top tab to
switch directly; each section remembers its selected cell and scroll position. Enter
toggles On/Off, cycles a designation or backend, or starts editing text/numbers
in place. Enter saves; Esc cancels an edit; Ctrl-U clears the input. F2 on a path
opens the file browser directly. Add PostgreSQL inserts an editable row on the
same Database tab. Wide tables scroll automatically to keep the selected cell visible.
Credentials stay masked, including while editing. File browsers show hidden
files by default. Removing
a drive or database row removes configuration only, never its files.
`hugpy-discovery settings --show` reports masked values and provenance (`--json`
for JSON). Values live in the shared `~/.config/hugpy/settings.json` local profile,
written atomically with owner-only permissions. Existing flat profiles appear as
rows without requiring migration. `XDG_CONFIG_HOME` and `XDG_DATA_HOME` control
base locations; explicit Hugpy directory settings take precedence.

## Models database (models-db-v1)

Discovery serves its evidence under the same models-db-v1 contract a Wrapper
serves its own models database with (`hugpy_terminal.models_db`): `hugpy_models.sqlite3`
is built from the selected evidence database, read-only and pinned to one
snapshot, into the contract's vocabulary (the `models` spine with store-relative
`model_uid`s, per-model section tables, global tables, per-partition digests and
a content-based `build_id`), then replaced atomically under a lock. The inspector
serves it at `/v1/telemetry/models-db/{status,digests,rows,build}` with `/health`
and `/v1/telemetry/service`, so Core's intake can mirror a Discovery host exactly
as it mirrors a worker. The builder rebuilds in the background after each
inventory build and whenever the evidence database changed. `hugpy-discovery
models-db build|status` runs or reports it from the command line; the
"Serve models database" setting turns building off while keeping an existing
file readable. Nothing here reaches Core: Core only pulls.

Run `hugpy-discovery` to launch with those settings. On an unconfigured first
launch the same settings editor opens. It inventories configured folders and,
unless disabled, the current user's standard Hugging Face cache into one
database outside model trees, resolves identities, then starts the inspector
at `http://127.0.0.1:8766` by default. Later launches reuse the inventory.
An existing foreign SQLite schema is inspected without automatic identity
writes. Provider lookups need no extra install. The earlier
standalone root configuration is imported once if no shared folders are saved.
Explicit subcommands remain available for fresh scans and other work.

Run `hugpy-discovery initialize` to refresh the configured live service's roots,
bind current file observations and units, derive geometry and measure drives and
placements. `--no-wait` starts the job and returns; progress remains in Status.
`POST /api/initialize` exposes the same operation as Build now. Initialization
checks database integrity before merging an existing publication. Index-only
damage is recovered with REINDEX after retaining a full backup, then checking
integrity and unchanged table-row counts; table corruption remains a failure.
An explicit preparation failure is reported as failed, never Database ready.
Initialization also reconciles copy locations with files already present on
declared drives. Current stat observations are published separately from transfer
completions; stale locations lose availability and previous observations remain
in the event ledger. Directory comparison includes device/inode/ctime when a
physical observation exists, so replacing a file or changing its metadata cannot
silently retain an old executable copy proof. Hash verification remains separate.

Discovery builds evidence up to engine testing: drives, inventory, file and
header facts, geometry, weight components, measured drive reads, routes,
movement and placements. Engine testing and everything after it (probes, loads,
memory ticks and fits, timing, calibration) is the Wrapper's, built from
Discovery's facts. Discovery imports nothing from a Wrapper store; tables from
earlier versions (`wrapper_*`, `engine_*_observations`, `memory_*`, `box_rates`,
`timing_*`) are no longer created or written and stay as they are in an
existing database. The removed code is in the archive snapshots up to 0.1.1.26.

Standalone inventory, verification and pre-engine evidence for a local model tree. Source model files are read without modification; observations and proofs are written to a separate SQLite database. This package has its own scanner, format readers, engine survey, and browser inspector. It does not import the wrapper application or use its model-record writer.

## Store layout

The model store is flat: `<creator>/<model>`, derived from each folder's own
records by `hugpy_discovery.identity.layout.flat_path`. `hugpy-discovery layout`
derives one folder; `--plan` lists every inventoried model root with merges,
collisions and gaps. See [docs/LAYOUT.md](docs/LAYOUT.md).

## Source layout

Modules are grouped by what they do; every internal import is relative, and
every module takes its standard-library, external, constant and generic-function
names from one place, `imports`:

| Package | Holds |
| --- | --- |
| `imports/` | `init_imports.py` (standard library), `module_imports.py` (external packages), `constants.py` (general constants), `functions/` (generic functions: environment, repositories, Hugging Face serialization, SQL access, kernel facts, formats, row persistence), `classes.py`; `__init__.py` re-exports them all |
| `sql/` | Each SQL file beside its Python tether, one package each: `store` (schema, migrations, stored queries), `preparation`, `drive_probes`, `locations`, `documentation`, `environment`, `operator_environment`, `workflow`, `formula_catalog`, `weight_components`, `history`, `provider_metadata` |
| `inventory/` | Scanning, analysis, dependencies, classification, engine survey and routes, quantification, file proofs (verification), the catalog |
| `identity/` | Identity resolution against Hugging Face (`huggingface/`) and Civitai |
| `drives/` | Filesystems, kernel drive events, designations, live changes, mount watch |
| `placements/` | Placements and accommodation, the copier (`movement`), copy history, the request socket and its call log |
| `viewer/` | The inspector (`viewer.py`, `viewer.html`), PostgreSQL browsing, progress reporting |
| `models_db/` | The models-db-v1 build and routes |

Everything loads with the package: `huggingface_hub` and `psycopg` are
required dependencies, and a missing one fails at import, never inside a
feature. Group `__init__.py` files carry a docstring only, so importing one
module never loads its whole group; import from the module (`.inventory.analysis`).

`hugpy-resources` is the canonical reference for shared generic functions,
format constants and MIME data; Discovery reaches them through
`module_imports`. Values computed from an external package at import time (the
models-db contract from `hugpy_terminal`, `sql.preparation.SAFE_ENV`) stay with
their module.

## Preparation and evidence

The [formula and validation reference](docs/formulas-and-validation.md) records
the offline test suite, ten formula contracts, pinned upstream sources and
existing geometry pointers. Schema v9 stores validation reports and a separate
static geometry review; incomplete memory totals remain NULL.

The [initial operator environment contract](docs/operator-environment-contract.md)
defines the eleven retained keys, their default pointers and migration aliases.
Schema v6 exposes this contract alongside the broader source audit; third-party
additions are deferred. Live service configuration has not yet been migrated.

## Assembly before derivation

The current review flow is:

```text
Saved documentation + eleven-key contract + environment source audit
                              ↓
Literal intake → declared stores/owners → filesystem and file locations
                              ↓
Provider identity → selected units and dependencies → current file proofs
                              ↓
pre_derivation_review: requirements passed or explicit blockers
                              ↓
Static geometry / memory evidence review → controlled engine checks (not attempted)
```

Use `prepare --stop-before-derivation` to refresh and connect the existing
evidence without computing geometry or memory scenarios. Repeat `--document`
to capture the associated Markdown in the same workflow:

```sh
.venv/bin/python -m hugpy_discovery prepare \
  --database artifacts/pre-engine-v9.sqlite3 \
  --env-file /etc/hugpy/wrapper.env --stop-before-derivation \
  --document README.md --document docs/operator-environment-contract.md
```

For a full documentation snapshot, pass all session documents, as in `save-docs`
below. With no `--document`, preparation binds the most recent saved import.
`preparation_context` pins the documentation import, source-registry run and
exact shared contract JSON/hash. `pre_derivation_review` joins current engine
candidates to units, ownership, filesystem identity, allowance, selected-file
verification and eight prerequisite gates. Context blockers remain explicit.
Preparation rechecks file stat identities and reuses completed proofs; it does
not read full weight payloads, fetch provider metadata or run benchmarks.

`current_execution_readiness` selects the latest completed preparation run;
historical candidates remain in `execution_plans`. Earlier geometry and memory
rows remain available, but deferred stages do not recompute or validate them.
The separate `formula-catalog --derive-static` command refreshes static evidence
after a passing offline suite, preserving that preparation history.
This joins the staging evidence flow; live Wrapper/Core configuration migration
and undeclared ownership remain separate outstanding work.

## Documentation snapshots

Schema v7 stores full Markdown content with source paths, SHA256 digests,
capture times and source stat identities. `documentation_current` exposes the
latest saved text for each document; `documentation_revisions` preserves older
content. Unchanged imports reuse a revision and record a new observation.
Source files remain in place. Capturing a document does not turn its historical
claims into current runtime evidence. Imports are explicit snapshots, not an
automatic filesystem watcher.

```sh
.venv/bin/python -m hugpy_discovery save-docs \
  --database artifacts/pre-engine-v9.sqlite3 \
  README.md docs/*.md \
  ../hugpy-settings/package/README.md
```

The inspector searches document text using its normal table search. Select a
row in `documentation_current` to read `content_markdown`. Markdown is displayed
as text, so embedded HTML and scripts are never executed.

## Build and inspect

```sh
.venv/bin/python -m hugpy_discovery build /path/to/models --database artifacts/discovery.sqlite3
.venv/bin/python -m hugpy_discovery serve /path/to/models --output artifacts --database artifacts/discovery.sqlite3
```

`build` creates a **new** database outside the model tree. An existing database is never overwritten. `--engine-python /path/to/python` may be repeated to include specific engine environments. The built-in survey checks a bounded set of local interpreters and native binaries before scanning models. Its results are scoped to this host and the surveyed executables; they do not describe remote fleet capacity.

The static `build` evidence path is:

1. Record engine package presence, Transformers loader registration, and host hardware.
2. Inventory the model tree, attribute directories/files to shared filesystem records, and inspect bounded file headers, manifests, and config documents.
3. Form weight sets, shard groups, and component dependencies. Keep alternative weight variants separate.
4. Derive per-bundle engine routes with explicit blockers or a `static-candidate` state.
5. Validate database references, estimate coverage, and source metadata stability.

`static-candidate` requires complete dependency evidence and a known loader mapping. Other routes retain `dependency-unresolved` or `loader-unresolved`. Even a `static-candidate` does **not** mean a model will load, fit memory, or run correctly. Static source stability is based on directory metadata plus hashes of inspected evidence bytes; `build` does not content-hash tensor payloads. The separate `prepare` and `verify` stages record readiness requirements and full-file proofs before a guarded engine check. Loader-specific files, custom code, version support, memory allocation, and runtime behavior remain to be checked by engine-specific execution in a later stage.

The original discovery prototype and its SQLite database remain in the wrapper staging tree as historical evidence. New discovery passes and the inspector should use this package and its own database.

## Status: building database

The inspector's home page is a **process ledger**, newest first: one line per process,
each built from recorded rows — a build or refresh (a `model_record_discovery_passes`
row), a copy/placement (an `accommodations` row, including those a wrapper requested
over the socket), an identity resolution session (continuous `model_identity_resolutions`)
and a file-proof session (continuous `file_hash_proofs`). The only derivation is the
session boundary: continuous activity is split where it idled for more than 30 minutes.
The running in-memory build leads the list, expanded, with its latest events as its
"now" line; a build/refresh expands to the models it touched, each with compact stage
marks (files, proofs, identity, classification, routes); any model row expands to its
full **build sheet** — every stage with when/source/values plus its `record_history`
change count and last change. Older processes expand on click.

Live updates arrive by **Server-Sent Events** from the inspector (`/api/status/stream`),
pushed whenever a progress event or a build start moves the inspector's event sequence;
nothing polls. The read-only JSON endpoints are:

| Route | Returns |
| --- | --- |
| `GET /api/status` | the one rolling in-memory state (unchanged; the CLI `follow` and other code use it) |
| `GET /api/status/stream` | the status snapshot as SSE, one `status` event per change |
| `GET /api/processes?limit=` | the ledger (running build prepended as a live process) |
| `GET /api/process?id=` | one process with its models (build/refresh) or steps/requests (copy) |
| `GET /api/model/build?dir=&worker=` | one model directory's full build sheet |

`hugpy-discovery status` prints the same ledger from the command line, reading the
configured (or `--database`) evidence database read-only: `--model DIR` prints one
model's build sheet, `--json` emits JSON, and `--follow` streams the running build over
`/api/status/stream` when the inspector is up (no polling). The interactive console
(the `hugpy-settings` terminal panel, opened by an interactive launch with the service
running) folds the former Run button into its **Status** tab — the same ledger with the
Build action on it — and adds a **View** tab that browses the built database read-only:
tables → rows (paged) → one row's fields, and a model's build sheet. The console's live
state follows the same event stream; its browsing reads the database read-only.

## Filesystem attribution

Schema v2 adds `filesystem_info`; `model_records.filesystem_id` and
`model_record_files.filesystem_id` reference it. Many models share one filesystem
row. File references describe the resolved file location, including a file on a
different filesystem from its model directory. The filesystem row records UUID
and PARTUUID when visible through `/dev/disk`, observed device major/minor and
path, filesystem type, mount entries/options, capacity and observation time.
Mount entries are plural because bind mounts can expose the same filesystem at
several paths with different options.

The primary key uses the host and observed filesystem UUID when available;
otherwise it uses the host, boot and observed filesystem device. UUID is not
assumed globally unique across hosts. Unknown identifiers remain NULL.
This is local observation, not fleet store identity or
a physical-disk topology inventory. Write/delete authority comes from the
drive's designation (see Placements); mount `rw` grants none of it. No write
probe or throughput benchmark runs here.

Opening a v1 database through the writable Store adds the references, leaving
historical rows unattributed. The read-only inspector does not migrate a database.
A fresh build populates current filesystem observations. Legacy `drive_*` columns
remain for compatibility; new consumers should join `filesystem_info`.

## Placements

Discovery owns its drives; the designation is the permission: **worker** read/write/delete,
**central** read/write (never deleted from), **immutable** and any undesignated drive read only
(`drive_designations.sync` sets `storage_roots.write_allowed`). The wrapper only requests
(`hugpy_discovery.placements`):

- `placements(db, key, variation)`: every (drive, reap route) the variation could be placed by,
  fastest first, with `read_seconds` (the drive's measured time to read it there, i.e. each later
  serve; a central copy stays a serve option). A route lists the worker copies it would archive
  to central and remove (bytes, assured, archive seconds, last read): `oldest_read` (LRU),
  `cheapest` (only copies central already holds when they suffice, else least archiving) and
  `fewest_removed`, each removing no more than the shortfall. Held copies and copies open or mapped
  by any process are never offered. The wrapper picks the
  route least likely to be called, by its own call history, and may ask ahead of a call.
- `accommodate(db, entry, mmap=False, pid=None)`: re-checks (re-plans the same route if the drive
  changed), places a hold for a disk-mmap placement, makes each removed copy assured on central
  (copying it there first; SHA-256 on both sides), removes it, then copies the variation (verified).
  Every request is an `accommodations` row with predicted and actual seconds, and its phases
  (plan, assure, remove, copy, refresh) are `accommodation_phases` rows.
- Predictions learn from history: every package the copier ships is a `drive_copies` row (seconds,
  format, position on both drives, the other traffic each carried). `transfers` times a file by
  its variation's last package to that drive, else the drive pair's rate for its format, else the pair's
  (page-cache hits excluded), and only then by the read/write model; `placements` scales that by
  the drives' traffic now and adds checking/archiving the removed copies and the median overhead.
- `unlock(db, hold_id)`: ends a hold; holds of a process that is gone are released automatically.

Requests come over a local Unix socket the service listens on (`placement_requests`):
`$XDG_RUNTIME_DIR/hugpy-discovery/requests.sock` (mode 0600), or a shared
`/run/hugpy-discovery/requests.sock` (0660, group `hugpy`) when that directory exists, or
`HUGPY_DISCOVERY_SOCKET`. The shared directory comes from a tmpfiles rule, so wrappers running as other
users in group `hugpy` can connect: `/etc/tmpfiles.d/hugpy-discovery.conf` holds
`d /run/hugpy-discovery 2770 <service user> hugpy -` (setgid, so the socket inherits the group).
The inspector listens on loopback only (`inspector_host` 127.0.0.1); hugpy-core serves the LAN.
One JSON object per line: `placements`, `accommodate` (queued, run by
one executor per drive, in order, resumed after a restart), `request` (status), `unlock`. Every
request is a `placement_requests` row with the kernel-attested requester (SO_PEERCRED uid/pid);
a hold is tied to that process and only the same user may unlock it. Clients call
`hugpy_discovery.placements.placement_requests.request(op, **message)`.

Everything is on record. `discovery_calls` is the call log: every `placements`, `accommodate`,
`queue`, `request` and `unlock` call with its channel (`socket`, `executor`, `library`), attested
caller, parent call, arguments, outcome and timing. `accommodation_steps` times each step and
names what it worked on; `drive_copies` stamps every file when it finished. The stored query
`timeline(:since, :until)` merges calls, requests, accommodations, steps, copies, drive events,
holds and hash proofs into one ordered log.

Every transfer ships as one package: the files the destination lacks travel as a single
uncompressed tar stream (consolidated, not compressed) into `<drive>/.hugpy-staging/<movement>/`,
each member hashed as it arrives; only a complete package (every member at its size and recorded
digest) lands, renamed into place with weights last. Each package is one `drive_copies` row.

An accommodation plans its copy before it removes anything; a drive that changed is re-planned
to the same route, or to one needing no removal, and otherwise refused (the requester chose what
to remove). Concurrent refreshes of one directory (the follower and an accommodation reacting to
the same copy) run once.

Any inventoried location holding a variation that is not a designated drive is listed as a
read-only `present` entry (immutable by default, `designated` False), as are designated
immutable drives that hold it.

Flow and terms: `/srv/hugpy/app/docs/discovery-wrapper-flow.html`.

## Model identity resolver

The HF resolver uses Discovery's own `huggingface.identity` adapter,
`ModelMetadataStore` and shared `serialize_model_info` helper, extracted from
Storage; no Storage package is needed for these lookups. For this staging checkout:

```sh
.venv/bin/python -m pip install -e .
.venv/bin/python -m hugpy_discovery resolve --database artifacts/discovery.sqlite3 --all
.venv/bin/python -m hugpy_discovery resolve --database artifacts/discovery.sqlite3 --model-dir /absolute/model/directory --offline
```

`--all` processes model directories with artifacts or configuration, skipping
empty inventory-only directories. `--worker` scopes a worker and `--limit` bounds
a batch. `build --resolve-identities` enriches a fresh inventory after its static
pass. Ordinary builds remain offline with respect to model providers.

The default cache is `provider-metadata.sqlite3` beside the discovery database
(or in the inspector's output directory). `--provider-cache` selects another
cache outside model trees. Successful responses persist without expiry;
`--refresh` explicitly replaces them, and `--offline` uses only cached results.
Errors remain distinct from empty search results and receive a ten-minute
retry delay. Credentials use Hugging Face's environment/saved token resolution;
requests are restricted to `https://huggingface.co`. Cache keys separate credential
scopes without storing tokens. No root provisioning helpers are imported.

The inspector serves these operations:

| Method and route | JSON body / query |
| --- | --- |
| `POST /api/identity/search` | `{"query":"model name","limit":5}` |
| `POST /api/identity/describe` | `{"model_id":"owner/repository","revision":"optional revision"}` |
| `POST /api/identity/resolve` | `{"model_dir":"/absolute/model/directory"}`; optional `worker` |
| `GET /api/identity/resolution` | `model_dir` and optional `worker`; reads the latest persisted result |

POST bodies must use `Content-Type: application/json`. Optional `offline` and
`refresh` booleans apply to the three POST operations. The initial provider is
`hf`; other provider names are rejected explicitly. The inspector's model-record
details also offer **Resolve identity**.

Schema v3 retains resolution history and candidate/provider evidence. Exact
repository hints plus matching local-inventory filenames and sizes can produce
`metadata-supported`; that status populates `hub_id` with an explicit
`hub_id_source`. Name-search matches stay candidates. Disagreement, ambiguity,
provider failures and offline cache misses remain visible. Comparisons use the
recorded scan and retain its input signature; this does not revalidate disk
contents. A provider's current commit is stored as `provider_revision`, never
silently assigned to the local `revision`. No weight hashing, downloading,
loading or geometry derivation is performed by identity resolution.


## Hugging Face tools

Discovery owns Hugging Face identity, metadata caching, search, repository size
lookups, snapshot audit and explicit repair/download helpers under
`src/hugpy_discovery/huggingface/`; every tool, token validation included,
ships with the base install. See [Hugging Face extraction](docs/huggingface-tools.md)
for source ownership, cache paths and examples. Storage's implementation remains
intact. File verification now uses the identical content-hashing implementation
from Resources, so Discovery no longer imports Storage.


## Optional: completing a model with hugpy-downloader

`features/downloads.py` joins Discovery to hugpy-downloader when that package is
installed (`importlib.util.find_spec('hugpy_downloader')`; it is never imported until
a function is called, and every entry point answers `{"available": false, "reason":
"hugpy-downloader is not installed"}` without it). It compares a model directory's
provider record (`huggingface.json`, `civitai.json`, `hugpy.json` `hub_id`, else the
recorded `hub.*` facts) with the files on disk, and hands exactly the missing ones to
the downloader's planner or queue; the downloader verifies each by sha256, merges in
place and then asks Discovery to `refresh` the directories it wrote.

```
python -m hugpy_discovery download tencent/Hunyuan3D-2 --plan      # missing files + the downloader's dry run
python -m hugpy_discovery download <model_dir> [--default-only]    # queue them for the hugpy-downloader daemon
python -m hugpy_discovery download <model_dir> --missing           # only the comparison (no network)
python -m hugpy_discovery download --list                          # recorded incomplete model directories
{"op": "download", "model_dir": "...", "plan": true}               # the same over the request socket
```

`--default-only` keeps to what the downloader fetches by default (a diffusers repo's
fp16 weights rather than their fp32/`.ckpt` twins; a Civitai version's primary weight).
`identity/huggingface/downloads.py` (the snapshot_download helpers) is superseded by it.

Internal imports are relative and at module level; none is deferred into a function.
Resource helpers resolve directly to their definitions in
`hugpy_resources.imports.functions` and `hugpy_resources.imports.constants`.

Shared metadata and exact NVML observations resolve through the Resources import
boundary. Discovery no longer imports Wrapper's NVML module. Discovery retains
provider/repository workflows and persistence; generic parsing stays in Resources
so lower-level consumers do not acquire a dependency on this application.

## Embedding in Wrapper

`inventory.build_database(..., store=host_store)` and
`inventory.create_database(..., store=host_store)` accept a host-owned Store.
Wrapper supplies its own Store and applies its own migrations before Discovery
writes inventory, filesystem, tensor and route evidence. Discovery neither
opens its standalone Store nor closes the supplied Store. The existing
standalone commands retain their own separate schema for standalone use.
`catalog.discover` supplies bounded traversal with host callbacks for configured
roots/exclusions, quant election and runtime eligibility.
