Hugpy settings

Every user-facing setting is defined once in Resources settings.domains, grouped by the package that owns it: shared (provider credentials), discovery (model folders, the evidence database, identity lookups, the inspector), database (backend choice and PostgreSQL connection) and wrapper (the assistant model, drive designations, budgets and transfer switches). A field's stores say where its value lives: local = the shared profile in ~/.config/hugpy/settings.json, box = a running Wrapper's box settings over its HTTP API. imports/constants/domains.py projects the flat views (FIELDS, LOCAL_FIELDS, BOX_SCHEMA, domain_fields).

local_settings is the local store: resolve(domains) gives every local field its value with provenance (environment override, saved value, terms default), update() validates and writes atomically with owner-only permissions, reset() removes overrides and report() masks secrets. local_panel.run(screen, domains) opens the one terminal editor for those domains — a section per domain with the same widgets, directory picker and provenance display as the Wrapper editor — and local_panel.show() prints the masked report. Hosts open the domains they use: Discovery opens discovery, database and shared (hugpy-discovery settings); the terminal opens every local domain (/settings local); Wrapper reads the discovery domain below its own saved box settings. Core reaches each Wrapper's wrapper domain through the fleet settings editor, one worker at a time. Existing remote settings editors use their host's API.

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 settings domains with the derived box schema (domains.py). Its __init__.py distributes these constants.