Hugpy settings

The shared settings layer extracted from Hugpy Wrapper's terminal harness. Wrapper and Hugpy Harness use this package directly instead of maintaining duplicate implementations. It depends on the shared hugpy-resources package for its constants and terms, and has no dependency on either application, model engines, or a database driver.

The layer owns settings snapshots and redaction, field schemas, inheritance reports, editing controls, terminal navigation, and the remote folder picker. The running Wrapper remains responsible for validation, persistence, resource admission, and applying changes through its existing HTTP API.

environment_contract.py owns the initial eleven operator-facing environment names, default/derivation pointers and migration aliases agreed on 2026-10-24. It is pure data plus presence-based input selection: canonical names win over aliases, explicit false/zero/empty are preserved, and disagreeing aliases remain unresolved. It does not import default resolvers, create directories, read the process environment or apply configuration. Discovery consumes this contract; live Wrapper/Core readers and installer writers still require migration.

from hugpy_settings.settings_view import show_settings, run_settings, snapshot

# gateway exposes api_key and models(); the host supplies endpoint discovery.
show_settings(gateway, base, model=model_key, as_json=True)
# A curses host can embed the same editor:
run_settings(screen, gateway, base, model=model_key, drain=drain, wait=wait)

drain is an optional event-draining callback. wait(title, operation) is an optional host callback for displaying progress around blocking work. Hosts own the terminal lifecycle. JSON and text reports remain available without curses.

Implementation modules:

• settings_view: snapshots, reports, and terminal entry points.
• imports/constants: schemas, setting vocabularies, validation groups, and API constants.
• settings_controls: parsing, HTTP updates, and editing workflows.
• settings_widgets: dropdowns, mouse handling, and remote directory browsing.

Wrapper's fitevict.cli.settings_* and Terminal's hugpy_terminal.tui.views.settings_* paths alias these same modules, preserving existing callers and shared module state. New callers should import hugpy_settings modules directly. Wrapper's schema was used as the source of record; Harness's stale video_allow_cpu UI entry was not carried forward.

For source development, install this package into each host's development environment before installing that host:

python3 -m pip install -e /path/to/staging/hugpy-resources
python3 -m pip install -e /path/to/staging/hugpy-settings/package

Both Debian builders build and bundle the shared wheel alongside their own wheel. HUGPY_SETTINGS_SOURCE can override the sibling source directory. The package must be published to the chosen Python index before distributing Wrapper or Harness wheels that depend on hugpy-settings==0.1.2 through it.

Source organization

The package source is src/hugpy_settings inside this package directory. imports/init_imports.py is the boundary for standard-library and external imports. imports/constants/ owns shared schemas, option lists and environment declarations; imports/classes.py owns shared contract and error types. imports/functions/ groups reusable parsing, layer-map syntax, formatting, redaction, comparisons and terminal input helpers.

The top-level modules retain Hugpy settings workflows, HTTP delivery and editing controls. Import schemas directly from hugpy_settings.imports.constants; reusable implementations are exported from the shared imports layer. Optional curses imports keep their original guarded or function-local timing.

The constants directory groups placement options (placement.py), validation rules (validation.py), drive roles (drives.py), editor controls (controls.py), environment contracts (environment.py), size units (units.py), redaction fields (redaction.py), HTTP contracts (api.py), and the pair and box schemas (knob_schema.py, box_schema.py). Its __init__.py distributes these constants.