Metadata-Version: 2.4
Name: hugpy-settings
Version: 0.1.7
Summary: Shared HTTP-backed settings editor and reports for Hugpy Wrapper and Harness
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: hugpy-resources<0.2,>=0.1.2.8

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

```python
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:

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