hugpy-settings 0.1.0__tar.gz

hugpy_settings-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: hugpy-settings
+Version: 0.1.0
+Summary: Shared HTTP-backed settings editor and reports for Hugpy Wrapper and Harness
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 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 uses only the Python standard library 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.
+
+```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.
+- `settings_schema`: model and box field descriptions.
+- `settings_controls`: parsing, HTTP updates, and editing workflows.
+- `settings_widgets`: dropdowns, mouse handling, and remote directory browsing.
+
+Wrapper's `fitevict.cli.settings_*` and Harness's
+`hugpy_harness.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-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.0` through it.

hugpy_settings-0.1.0/README.md

@@ -0,0 +1,49 @@
+# 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 uses only the Python standard library 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.
+
+```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.
+- `settings_schema`: model and box field descriptions.
+- `settings_controls`: parsing, HTTP updates, and editing workflows.
+- `settings_widgets`: dropdowns, mouse handling, and remote directory browsing.
+
+Wrapper's `fitevict.cli.settings_*` and Harness's
+`hugpy_harness.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-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.0` through it.

hugpy_settings-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugpy-settings"
+version = "0.1.0"
+description = "Shared HTTP-backed settings editor and reports for Hugpy Wrapper and Harness"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["hugpy_settings*"]

hugpy_settings-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hugpy_settings-0.1.0/src/hugpy_settings/__init__.py

@@ -0,0 +1,5 @@
+"""Shared HTTP-backed settings UI for Hugpy Wrapper and Harness.
+
+Import terminal/report entry points from hugpy_settings.settings_view.
+The package has no dependency on either host application.
+"""

hugpy_settings-0.1.0/src/hugpy_settings/settings_controls.py

@@ -0,0 +1,328 @@
+"""Stdlib editing controls for the shared Wrapper and Harness settings UI."""
+from __future__ import annotations
+
+try:
+    import curses
+except ImportError:  # JSON/text reporting remains available without a terminal backend.
+    curses = None
+import json
+import math
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .settings_schema import KNOB_SCHEMA, BOX_SCHEMA
+from .settings_widgets import CANCEL, SettingsWidgets, mouse_event
+
+ROLES = [('Central library', 'central'), ('Worker storage', 'worker'), ('Read-only source', 'immutable'),
+         ('Inherit designation (remove this override)', None)]
+
+
+def parse_value(spec, text):
+    if text == '':
+        return None
+    kind = spec.get('type')
+    if kind in ('number', 'int'):
+        try:
+            value = int(text) if kind == 'int' else float(text)
+        except (ValueError, TypeError):
+            raise ValueError('Enter a whole number.' if kind == 'int' else 'Enter a number.') from None
+        if not math.isfinite(value) or ('min' in spec and value < spec['min']) or ('max' in spec and value > spec['max']):
+            raise ValueError('Value is outside the allowed range.')
+        return value
+    if kind == 'list':
+        values = [s.strip() for s in text.split(',') if s.strip()]
+        if spec.get('options') and any(v not in spec['options'] for v in values):
+            raise ValueError('Choose values from the offered options.')
+        return values
+    return text
+
+
+def write_endpoint(gateway, base, path, body, timeout):
+    """One merge update; never retry a write or follow it to another origin."""
+    headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
+    if getattr(gateway, 'api_key', ''):
+        headers['Authorization'] = 'Bearer ' + gateway.api_key
+    request = urllib.request.Request(base + path, data=json.dumps(body).encode(), headers=headers, method='POST')
+    class NoRedirect(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, *args, **kwargs): return None
+    try:
+        with urllib.request.build_opener(NoRedirect).open(request, timeout=min(timeout, 10)) as response:
+            data = json.load(response)
+    except urllib.error.HTTPError as exc:
+        try:
+            error = json.loads(exc.read()).get('error', {})
+            message = error.get('message') if isinstance(error, dict) else error
+        except (OSError, ValueError):
+            message = None
+        raise ValueError('HTTP %s: %s' % (exc.code, message or exc.reason)) from None
+    if not isinstance(data, dict) or data.get('error') or data.get('ok') is False:
+        raise ValueError('Wrapper rejected the setting: ' + str(data.get('error') if isinstance(data, dict) else 'invalid response'))
+    return data
+
+
+class SettingsEditor(SettingsWidgets):
+    def __init__(self, screen, gateway, base, model=None, timeout=30, drain=None, wait=None):
+        self.screen, self.gateway, self.base = screen, gateway, base
+        self.model, self.timeout, self.drain, self.wait = model, timeout, drain, wait
+
+    def put(self, y, text, attr=0):
+        h, w = self.screen.getmaxyx()
+        if 0 <= y < h and w > 1:
+            text = ''.join(c if c.isprintable() else ' ' for c in str(text))
+            try:
+                self.screen.addnstr(y, 0, text, w - 1, attr)
+            except curses.error:
+                pass
+
+    def key(self):
+        key = self.screen.getch()
+        if self.drain:
+            self.drain()
+        return key
+
+    def choose(self, title, labels, selected=0):
+        if not labels:
+            return None
+        selected = max(0, min(selected, len(labels) - 1))
+        while True:
+            self.screen.erase()
+            h, w = self.screen.getmaxyx()
+            count = max(1, h - 5)
+            self.put(0, title, curses.A_BOLD)
+            start = selected // count * count
+            for y, label in enumerate(labels[start:start + count], 2):
+                i = start + y - 2
+                self.put(y, ('> ' if i == selected else '  ') + label,
+                         curses.A_REVERSE if i == selected else 0)
+            self.put(h - 1, 'Up/Down choose · Enter select · Esc cancel')
+            self.screen.refresh()
+            key = self.key()
+            if key == curses.KEY_MOUSE:
+                event = mouse_event(self.screen)
+                if event and event['wheel']:
+                    key = curses.KEY_UP if event['wheel'] < 0 else curses.KEY_DOWN
+                elif event and event['click'] and 2 <= event['y'] < 2 + min(count, len(labels) - start):
+                    if h >= 6 and w >= 20:
+                        return start + event['y'] - 2
+                else:
+                    continue
+            if key in (27, curses.KEY_F10, 3, 4): return None
+            if key in (10, 13, curses.KEY_ENTER) and h >= 6 and w >= 20: return selected
+            if key == curses.KEY_UP: selected = max(0, selected - 1)
+            elif key == curses.KEY_DOWN: selected = min(len(labels) - 1, selected + 1)
+            elif key == curses.KEY_PPAGE: selected = max(0, selected - count)
+            elif key == curses.KEY_NPAGE: selected = min(len(labels) - 1, selected + count)
+            elif key == curses.KEY_HOME: selected = 0
+            elif key == curses.KEY_END: selected = len(labels) - 1
+
+    def text(self, title, current='', help='Empty = inherit; Ctrl-U clears'):
+        text = str(current)
+        while True:
+            self.screen.erase()
+            h, w = self.screen.getmaxyx()
+            self.put(0, title, curses.A_BOLD)
+            # Keep the cursor end visible for long remote paths.
+            self.put(2, (text + '_')[-max(1, w - 1):])
+            self.put(4, help)
+            self.put(h - 1, 'Enter continue · Backspace edit · Esc cancel')
+            self.screen.refresh()
+            key = self.key()
+            if key in (27, curses.KEY_F10, 3, 4): return CANCEL
+            if key in (10, 13, curses.KEY_ENTER) and h >= 6 and w >= 20: return text.strip()
+            if key in (curses.KEY_BACKSPACE, 127, 8): text = text[:-1]
+            elif key == 21: text = ''
+            elif 32 <= key <= 126: text += chr(key)
+
+    def message(self, title, message):
+        self.choose(title, [str(message), 'Back'])
+
+    def fetch(self, title, fn):
+        return self.wait(title, fn) if self.wait else fn()
+
+    def save(self, path, settings, model=None):
+        body = {'settings': settings}
+        if model is not None:
+            body['model_key'] = model
+        return self.save_body(path, body)
+
+    def save_body(self, path, body):
+        changes = body.get('settings', body)
+        names = {s['key']: s['label'] for s in KNOB_SCHEMA + BOX_SCHEMA}
+        descriptions = []
+        for key, value in changes.items():
+            if key in ('drive_roles', 'drive_budgets'):
+                role_names = {role: name for name, role in ROLES}
+                for drive_path, setting in value.items():
+                    shown = role_names[setting] if key == 'drive_roles' else ('inherit' if setting is None else str(setting) + ' GiB')
+                    descriptions.append(drive_path + ': ' + shown)
+            else:
+                shown = 'inherit' if value is None else ('on' if value else 'off') if isinstance(value, bool) else str(value)
+                descriptions.append(names.get(key, key.replace('_', ' ').title()) + ': ' + shown)
+        label = '; '.join(descriptions)
+        scope = (' · model ' + str(body['model_key'])) if body.get('model_key') else ''
+        if self.choose('Save to Wrapper ' + self.base + scope + '?', ['Back', 'Save ' + label]) != 1:
+            return False
+        try:
+            if self.screen is not None:
+                self.put(0, 'Saving Wrapper settings…', curses.A_BOLD)
+                self.screen.refresh()
+            write_endpoint(self.gateway, self.base, path, body, self.timeout)
+        except (OSError, ValueError) as exc:
+            self.message('Save failed — refresh before retrying', str(exc))
+            return False
+        return True
+
+    def select_value(self, spec, current, data):
+        kind = spec.get('type')
+        if kind in ('bool', 'select'):
+            values = [None] + ([True, False] if kind == 'bool' else list(spec.get('options') or []))
+            labels = ['Inherit (remove override)'] + [('On' if v else 'Off') if isinstance(v, bool) else str(v) for v in values[1:]]
+            selected = values.index(current) if current in values else 0
+            pick = self.dropdown(spec['label'], labels, selected)
+            return CANCEL if pick is None else values[pick]
+        if kind == 'list' and spec.get('options'):
+            values = list(spec['options'])
+            chosen = set(current or [])
+            while True:
+                labels = ['Apply selection', 'Inherit (remove override)'] + [
+                    ('[x] ' if v in chosen else '[ ] ') + v for v in values]
+                pick = self.choose(spec['label'] + ' · toggle choices, then apply', labels)
+                if pick is None: return CANCEL
+                if pick == 0: return [v for v in values if v in chosen]
+                if pick == 1: return None
+                value = values[pick - 2]
+                chosen.symmetric_difference_update([value])
+        if kind in ('model', 'quant'):
+            try:
+                records = self.fetch('Reading model options', self.gateway.models)
+            except (OSError, ValueError) as exc:
+                self.message('Model catalog unavailable', str(exc))
+                return CANCEL
+            values = sorted({r.get('file') if kind == 'quant' else r.get('id') for r in records
+                             if r.get('id') and (kind != 'quant' or r['id'] == self.model)} - {None, ''})
+            pick = self.choose(spec['label'], ['Inherit (remove override)'] + values + ['Enter a value'])
+            if pick is None: return CANCEL
+            if pick == 0: return None
+            if pick <= len(values): return values[pick - 1]
+        default = ', '.join(str(v) for v in current) if isinstance(current, list) else str(current) if current is not None else ''
+        while True:
+            text = self.text(spec['label'], default, spec.get('help') or 'Empty = inherit; Ctrl-U clears')
+            if text is CANCEL: return CANCEL
+            try:
+                return parse_value(spec, text)
+            except ValueError as exc:
+                self.message('Invalid value', str(exc))
+                default = text
+
+    def drive_path(self, data, budget=False):
+        storage = data.get('storage') or {}
+        drives = storage.get('drives', []) + storage.get('central_drives', [])
+        drives = [d for d in drives if d.get('path') and (not budget or d.get('role') in ('worker', 'central'))]
+        labels = [d['path'] + ' · ' + dict((v, k) for k, v in ROLES).get(d.get('role'), d.get('role') or '') for d in drives]
+        pick = self.choose('Choose a drive on the Wrapper host', labels + ['Browse disks and folders on the Wrapper host…', 'Enter a directory path on the Wrapper host'])
+        if pick is None: return CANCEL
+        if pick < len(drives): return drives[pick]['path']
+        if pick == len(drives): return self.browse_directory(data)
+        path = self.text('Directory path on the Wrapper host', help='Absolute directory path; Wrapper checks it exists')
+        if path is CANCEL: return CANCEL
+        if not path.startswith('/'):
+            self.message('Invalid path', 'Enter an absolute directory path on the Wrapper host.')
+            return CANCEL
+        return path
+
+    def drive(self, key, data):
+        if 'storage' in data.get('errors', {}):
+            self.message('Drive settings unavailable', data['errors']['storage'])
+            return
+        path = self.drive_path(data, budget=key == 'drive_budgets')
+        if path is CANCEL: return
+        box = (data.get('box') or {}).get('box_only') or {}
+        if key == 'drive_roles':
+            current = (box.get(key) or {}).get(path)
+            pick = self.dropdown('Designation for ' + path, [r[0] for r in ROLES],
+                               next((i for i, r in enumerate(ROLES) if r[1] == current), 3))
+            if pick is None: return
+            value = ROLES[pick][1]
+        else:
+            value = self.select_value({'type': 'number', 'label': 'Budget in GiB for ' + path, 'min': 0,
+                                       'help': 'Empty = inherit. Must fit within the drive designation.'},
+                                      (box.get(key) or {}).get(path), data)
+            if value is CANCEL: return
+        # Send just the selected path. The backend merges into its latest map.
+        return self.save('/v1/settings/box', {key: {path: value}})
+
+    def fields(self, section, data):
+        """Editable rows, in the same order for display and Enter dispatch."""
+        if section == 'Connections':
+            return []
+        if section == 'Worker':
+            if 'limits' in data.get('errors', {}):
+                return []
+            limits = data.get('limits') or {}
+            rows = []
+            for key, label, kind in [('gpu_limit', 'VRAM limit (GiB)', 'number'),
+                                     ('ram_limit', 'RAM limit (GiB)', 'number'),
+                                     ('storage_limit', 'Storage limit (GiB)', 'number'),
+                                     ('cpu_limit', 'CPU limit (physical cores)', 'int')]:
+                current = limits.get(key)
+                if current is not None and kind == 'number':
+                    current /= 2**30
+                rows.append(({'key': key, 'label': label, 'type': kind, 'min': 0,
+                              'help': 'Live limit; Core may replace it on registration. Empty = no local limit.'}, current))
+            return rows
+        pair = section == 'Model'
+        if (pair and not self.model) or ('pair' if pair else 'box') in data.get('errors', {}):
+            return []
+        box = data.get('box') or {}
+        accepted = set(box.get('accepts') or []) | set(box.get('box_only_accepts') or [])
+        schema = KNOB_SCHEMA if pair else [s for s in KNOB_SCHEMA + BOX_SCHEMA if s['key'] in accepted]
+        if section in ('Drives', 'Central'):
+            schema = [s for s in schema if s.get('group') == 'drives']
+        elif section == 'Auto':
+            schema = [s for s in schema if s.get('group') != 'drives']
+        own = ((data.get('pair') or {}).get('settings') or {}) if pair else {
+            **(box.get('settings') or {}), **(box.get('box_only') or {})}
+        return [(spec, own.get(spec['key'])) for spec in schema]
+
+    def edit(self, section, data, selected=None):
+        if section == 'Connections':
+            self.message('Connection settings', 'Server addresses and access settings come from the Wrapper installation configuration.')
+            return
+        if section == 'Worker':
+            return self.worker_limits(data, selected=selected)
+        pair = section == 'Model'
+        if pair and not self.model:
+            self.message('Choose a model first', 'Open settings from the highlighted model in the model picker.')
+            return
+        source = 'pair' if pair else 'box'
+        if source in data.get('errors', {}):
+            self.message('Settings unavailable', data['errors'][source])
+            return
+        rows = self.fields(section, data)
+        labels = [spec['label'] + ': ' + (json.dumps(value, ensure_ascii=False) if value is not None else 'inherit')
+                  for spec, value in rows]
+        pick = self.choose(section + ' · choose a setting', labels) if selected is None else selected
+        if pick is None or not 0 <= pick < len(rows): return
+        spec, current = rows[pick]
+        key = spec['key']
+        if key in ('drive_roles', 'drive_budgets'):
+            return self.drive(key, data)
+        value = self.select_value(spec, current, data)
+        if value is CANCEL: return
+        return self.save('/v1/settings/pair' if pair else '/v1/settings/box', {key: value}, self.model if pair else None)
+
+    def worker_limits(self, data, selected=None):
+        if 'limits' in data.get('errors', {}):
+            self.message('Resource limits unavailable', data['errors']['limits'])
+            return
+        rows = self.fields('Worker', data)
+        pick = self.choose('Live worker limits · Core may replace these on registration',
+                           [spec['label'] for spec, _ in rows]) if selected is None else selected
+        if pick is None or not 0 <= pick < len(rows): return
+        spec, current = rows[pick]
+        value = self.select_value(spec, current, data)
+        if value is CANCEL: return
+        if value is not None and spec['type'] == 'number':
+            value = int(value * 2**30)
+        return self.save_body('/limits', {spec['key']: value})

hugpy_settings-0.1.0/src/hugpy_settings/settings_schema.py

@@ -0,0 +1,109 @@
+"""Wrapper terminal setting descriptions, adapted from Core config/knob_schema.
+
+The running Wrapper accepts list gates box controls. No Core dependency.
+"""
+from __future__ import annotations
+
+# The per-(worker, model) knobs the wrapper honours (fitevict pair_settings).
+# The console builds its editor from this list and Core validates against it.
+KNOB_SCHEMA = [
+    {'key':'min_decode_tok_s','label':'Decode target (tokens/s)','type':'number','min':0.01,'group':'cpu',
+     'help':'Minimum predicted decode throughput. Derives a CPU minimum when a curve is known; an unmeasured trial is explicitly unknown, never a throughput guarantee.'},
+    {'key':'disk_mmap','label':'Disk-backed mmap','type':'bool','group':'placement',
+     'help':'Allow native GGUF CPU inference backed by disk as a final Auto fallback. Default off. Slowest or low-quality tolerance permits it.'},
+    {'key':'disk_mmap_cache_gib','label':'Mapped working set (GiB)','type':'number','min':0.25,'group':'placement',
+     'help':'RAM reservation for mapped weight pages, plus all anonymous memory. Default 4 GiB. This is not a kernel RSS limit.'},
+    {'key': 'auto_goal', 'label': 'Auto goal', 'type': 'select', 'options': ['quality', 'fast'],
+     'group': 'placement', 'help': 'How Auto ranks the admissible placements: best quality or fastest. None = inherit the box blanket; with no preference anywhere every model lists its load options.'},
+    {'key': 'tolerance', 'label': 'Tolerance', 'type': 'select', 'options': ['fast', 'slow', 'slowest', 'low-quality'],
+     'group': 'placement', 'help': 'The floor on the placement ladder: fast = GPU only; slow = + MoE split; slowest = + RAM placements; low-quality = + 4-bit and lower quants. Tolerance determines eligibility; Auto goal ranks the permitted placements.'},
+    {'key': 'alloc_mode', 'label': 'Placement', 'type': 'select', 'options': ['gpu-only', 'ram-only', 'max-gpu', 'max-ram', 'explicit'],
+     'group': 'placement', 'help': 'Pin a placement mode. explicit = the MoE expert split / explicit budgets. Empty = Auto (GPU only, then MoE split, then 4-bit, then RAM).'},
+    {'key': 'gguf_file', 'label': 'Quant file', 'type': 'quant', 'group': 'placement',
+     'help': 'Serve this quant file instead of the elected one. Empty = the elected quant with Auto stepping.'},
+    {'key': 'moe', 'label': 'MoE expert split', 'type': 'bool', 'group': 'placement',
+     'help': 'Keep the MoE experts in host RAM and the attention on the GPU.'},
+    {'key': 'n_gpu_layers', 'label': 'GPU layers', 'type': 'int', 'min': -1, 'max': 1000, 'group': 'placement',
+     'help': '-1 = every layer on the GPU; 0 = none; N = an explicit split.'},
+    {'key': 'n_cpu_moe', 'label': 'MoE layers on CPU', 'type': 'int', 'min': 0, 'max': 1000, 'group': 'placement'},
+    {'key': 'gpu_mem_gib', 'label': 'VRAM budget (GiB)', 'type': 'number', 'min': 0, 'group': 'placement'},
+    {'key': 'cpu_mem_gib', 'label': 'RAM budget (GiB)', 'type': 'number', 'min': 0, 'group': 'placement'},
+    {'key': 'cpu_cores', 'label': 'CPU cores', 'type': 'int', 'min': 1, 'max': 1024, 'group': 'cpu'},
+    {'key': 'cpu_floor_cores', 'label': 'CPU floor (cores)', 'type': 'int', 'min': 0, 'max': 1024, 'group': 'cpu',
+     'help': 'A host-resident placement is admissible only if it would get at least this many physical cores.'},
+    {'key': 'kv_cache_type', 'label': 'KV cache type', 'type': 'select', 'options': ['f16', 'q8_0', 'q4_0'], 'group': 'context'},
+    {'key': 'flash_attn', 'label': 'Flash attention', 'type': 'bool', 'group': 'context'},
+    {'key': 'ctx_preset', 'label': 'Context preset', 'type': 'select', 'options': ['low', 'medium', 'high', 'xhigh'], 'group': 'context'},
+    {'key': 'ctx_pct', 'label': 'Max context (% of trained)', 'type': 'int', 'min': 1, 'max': 100, 'group': 'context'},
+    {'key': 'ctx_min_pct', 'label': 'Min context (% of trained)', 'type': 'int', 'min': 1, 'max': 100, 'group': 'context'},
+    {'key': 'ctx_range_enabled', 'label': 'Context range', 'type': 'bool', 'group': 'context',
+     'help': 'Allow a polite-eviction window between min and max context.'},
+    {'key': 'ctx_yield', 'label': 'Shrink instead of evict', 'type': 'bool', 'group': 'context'},
+    {'key': 'ctx_restore', 'label': 'Grow back when idle', 'type': 'bool', 'group': 'context'},
+    {'key': 'max_wait_s', 'label': 'Max wait (seconds)', 'type': 'int', 'min': 1, 'max': 86400, 'group': 'admission'},
+    {'key': 'residency', 'label': 'Residency', 'type': 'select', 'options': ['static'], 'group': 'admission',
+     'help': 'static = never evicted once loaded.'},
+    {'key': 'quality_alternatives', 'label': 'Quality alternatives', 'type': 'select', 'options': ['auto', 'none'], 'group': 'admission',
+     'help': 'Whether Auto may step down to a smaller approved quant of this model.'},
+    {'key': 'blocked', 'label': 'Blocked', 'type': 'bool', 'group': 'admission', 'help': 'Refuse calls for this model on this worker.'},
+    {'key': 'fit_order', 'label': 'Fit order', 'type': 'list', 'group': 'admission',
+     'help': 'Comma-separated steps for @fit: gpu-only, moe, max-gpu, 4bit-gpu-only, 4bit-max-gpu, ram-only.'},
+    # The original console's own knobs (quant preference list, 4-bit, explicit
+    # placement bands and priorities): stored on the pair like every other knob.
+    # Blanket preferences (directions/auto-multiplexing): what Auto may change.
+    {'key': 'allowed_placements', 'label': 'Allowed placements', 'type': 'list', 'group': 'admission',
+     'options': ['gpu-only', 'moe', '4bit', 'ram-only', 'max-ram', 'max-gpu'],
+     'help': 'The placements Auto may use. Empty = all (GPU preferred). Remove ram-only to disable CPU execution.'},
+    {'key': 'wait_before_quality', 'label': 'Wait before a quality change', 'type': 'bool', 'group': 'admission',
+     'help': 'Wait (within max wait) for expected room — a call in flight finishing — before stepping to an approved alternative.'},
+    {'key': 'resident_priority', 'label': 'Resident priority', 'type': 'int', 'min': 0, 'max': 1000, 'group': 'admission',
+     'help': 'Eviction band: a higher priority resident is evicted after every lower one.'},
+    {'key': 'latency_target_s', 'label': 'Latency target (s)', 'type': 'number', 'min': 0, 'group': 'admission',
+     'help': 'An admission preference: a measured response estimate above it ranks after every plan within it.'},
+    {'key': 'quants', 'label': 'Quant preference', 'type': 'list', 'group': 'placement',
+     'help': 'Ordered quant files; the allocated quant is the first that fits.'},
+    {'key': 'bnb_4bit', 'label': '4-bit (bitsandbytes)', 'type': 'bool', 'group': 'placement'},
+    {'key': 'attention_gpu_layers', 'label': 'Attention layers on GPU', 'type': 'int', 'min': 0, 'max': 10000, 'group': 'placement'},
+    {'key': 'experts_cpu_layers', 'label': 'Expert layers on CPU', 'type': 'int', 'min': 0, 'max': 10000, 'group': 'placement'},
+    {'key': 'explicit_spill', 'label': 'Explicit spill', 'type': 'select', 'options': ['prefer-ram', 'prefer-gpu'], 'group': 'placement'},
+    {'key': 'gpu_model_pct', 'label': 'Model % on GPU', 'type': 'number', 'min': 0, 'group': 'placement'},
+    {'key': 'leniency_pct', 'label': 'Leniency %', 'type': 'number', 'min': 0, 'group': 'placement'},
+    {'key': 'priority_device', 'label': 'Priority device', 'type': 'select', 'options': ['gpu', 'ram'], 'group': 'placement'},
+    {'key': 'gpu_mem_gib_deviation_pct', 'label': 'VRAM band %', 'type': 'number', 'min': 0, 'group': 'placement'},
+    {'key': 'cpu_mem_gib_deviation_pct', 'label': 'RAM band %', 'type': 'number', 'min': 0, 'group': 'placement'},
+    {'key': 'ctx_deviation_pct', 'label': 'Context band %', 'type': 'number', 'min': 0, 'group': 'context'},
+    {'key': 'threads', 'label': 'Threads', 'type': 'int', 'min': 1, 'max': 4096, 'group': 'cpu'},
+    {'key': 'priority', 'label': 'Priority', 'type': 'number', 'min': 0, 'group': 'admission'},
+]
+KNOBS_BY_KEY = {k['key']: k for k in KNOB_SCHEMA}
+
+
+# The BOX's own settings (wrapper /v1/settings/box, 0.1.111+): not per model, never inherited by
+# one — the help model that reads plain language, and the drives (roles, budgets, the movers).
+BOX_SCHEMA = [
+    {'key': 'assist_model', 'label': 'Assistant model', 'type': 'model', 'group': 'box',
+     'help': 'The catalog model that turns plain language said to HugpyHelper into one of its commands.'},
+    {'key': 'drive_roles', 'label': 'Drive roles', 'type': 'drive_roles', 'options': ['central', 'worker', 'immutable'],
+     'group': 'drives', 'help': 'Per path: central = the source of record (loaded from, uploaded from, copied to; never '
+     'reaped); worker = the fast drive the box loads from, within its budget, reaped to fit; immutable = read in place, '
+     'never written. Over the env designation (HUGPY_CENTRAL_DRIVES / HUGPY_WORKER_DRIVES); MODELS_HOME is a worker '
+     'drive by default.'},
+    {'key': 'drive_budgets', 'label': 'Drive budgets (GiB)', 'type': 'drive_budgets', 'group': 'drives',
+     'help': 'Per worker or central drive: the GiB of models it may hold. Never above the drive (or its env designation).'},
+    {'key': 'upload_to_worker', 'label': 'Upload to worker drive', 'type': 'bool', 'group': 'drives',
+     'help': 'A called model that lives only on a central drive is copied whole to the worker drive first, then loaded '
+     'from there. On by default under a core (a central is every worker’s central: the second load is never a time trap), off wrapper-only (env HUGPY_UPLOAD_TO_WORKER).'},
+    {'key': 'reap_to_fit', 'label': 'Reap to fit', 'type': 'bool', 'group': 'drives',
+     'help': 'An upload that does not fit removes worker copies, least recently called first, never resident or '
+     'protected, only when a central drive holds the exact duplicate. On by default under a core, off wrapper-only (env '
+     'HUGPY_REAP_TO_FIT); set on, it turns the other two on unless they are set either way.'},
+    {'key': 'copy_to_central', 'label': 'Copy to central', 'type': 'bool', 'group': 'drives',
+     'help': 'A model whose home is a worker drive is copied to a central drive with room (event-driven, in the '
+     'background). Off by default (env HUGPY_COPY_TO_CENTRAL) — under a core central’s own copier owns writes to central.'},
+    {'key': 'central_serves', 'label': 'Central serves', 'type': 'bool', 'group': 'drives',
+     'help': 'May a load read a model straight from a central drive. Off by default when the box is under a core '
+     '(central is storage only: the model is staged to a worker drive first, and a call that cannot be staged is refused '
+     'with the reason); on for a wrapper-only build. Env HUGPY_CENTRAL_SERVES (wrapper 0.1.119).'},
+]
+
+

hugpy_settings-0.1.0/src/hugpy_settings/settings_view.py

@@ -0,0 +1,385 @@
+"""Settings snapshots and an editable stdlib terminal viewer."""
+from concurrent.futures import ThreadPoolExecutor
+import datetime
+import json
+import os
+from pathlib import Path
+import sys
+import textwrap
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .settings_controls import SettingsEditor
+from .settings_widgets import settings_input, mouse_event
+
+AUTO_KEYS = ("auto_goal", "tolerance", "quality_alternatives", "allowed_placements", "max_wait_s",
+             "wait_before_quality", "min_decode_tok_s", "cpu_floor_cores", "resident_priority",
+             "latency_target_s", "disk_mmap", "disk_mmap_cache_gib")
+MODEL_KEYS = AUTO_KEYS + ("alloc_mode", "gguf_file", "quants", "moe", "bnb_4bit", "n_gpu_layers",
+                         "n_cpu_moe", "gpu_mem_gib", "cpu_mem_gib", "cpu_cores", "kv_cache_type",
+                         "flash_attn", "ctx_preset", "ctx_pct", "ctx_min_pct", "ctx_range_enabled",
+                         "ctx_yield", "ctx_restore", "residency", "blocked", "fit_order")
+ROLE_LABELS = {"central": "Central library", "worker": "Worker storage", "immutable": "Read-only source"}
+
+
+def redact(value):
+    if isinstance(value, dict):
+        out = {}
+        for key, item in value.items():
+            name = str(key).lower()
+            secret = name in ("api_key", "token", "secret", "password", "authorization", "secret_hash") or name.endswith(
+                ("_api_key", "_token", "_password", "_secret", "_secret_hash"))
+            summary = isinstance(item, dict) and set(item) <= {"configured", "display", "source"}
+            out[key] = ("****" if item else "not set") if secret and not summary else redact(item)
+        return out
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    return value
+
+
+def local_record(base):
+    config = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+    for path in (config / "hugpy/wrapper.endpoint.json", Path("/etc/hugpy/wrapper.endpoint.json")):
+        try:
+            record = json.loads(path.read_text())
+            if str(record.get("url", "")).rstrip("/") == base.rstrip("/"):
+                return record
+        except (OSError, ValueError):
+            pass
+    return {}
+
+
+def read_endpoint(gateway, base, path, timeout):
+    headers = {"Accept": "application/json"}
+    if getattr(gateway, "api_key", ""):
+        headers["Authorization"] = "Bearer " + gateway.api_key
+    request = urllib.request.Request(base + path, headers=headers, method="GET")
+    with urllib.request.urlopen(request, timeout=min(timeout, 10)) as response:
+        data = json.load(response)
+    if not isinstance(data, dict):
+        raise ValueError("invalid settings response")
+    return data
+
+
+def snapshot(gateway, base, model=None, timeout=30):
+    base = base.rstrip('/')
+    if base.endswith('/v1'):
+        base = base[:-3]
+    paths = {"health": "/health", "limits": "/limits", "box": "/v1/settings/box",
+             "storage": "/v1/drives", "runtime": "/v1/settings/runtime", "keys": "/v1/keys?all=1"}
+    if model:
+        paths["pair"] = "/v1/settings/pair?" + urllib.parse.urlencode({"model_key": model})
+    data = {"read_only": True, "endpoint": base, "model": model, "errors": {},
+            "captured_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            "client_api_key": {"configured": bool(getattr(gateway, "api_key", "")),
+                               "display": "****" if getattr(gateway, "api_key", "") else "not set"}}
+    with ThreadPoolExecutor(max_workers=len(paths)) as pool:
+        pending = {name: pool.submit(read_endpoint, gateway, base, path, timeout) for name, path in paths.items()}
+        for name, future in pending.items():
+            try:
+                data[name] = future.result()
+            except (OSError, ValueError) as exc:
+                data[name] = {}
+                data["errors"][name] = ("Admin API key required" if getattr(exc, "code", None) in (401, 403)
+                                        else str(exc))
+    if not data.get("runtime"):
+        record = local_record(base)
+        if record.get("runtime_settings"):
+            data["runtime"] = record["runtime_settings"]
+            data["runtime_source"] = record.get("runtime_settings_source", "local install record")
+            data["errors"].pop("runtime", None)
+    else:
+        data["runtime_source"] = "running Wrapper API"
+    return redact(data)
+
+
+def knob_rows(data, keys):
+    pair, box = data.get("pair") or {}, data.get("box") or {}
+    own = pair.get("settings") or {}
+    blanket = pair.get("box") if pair.get("box") is not None else box.get("settings") or {}
+    effective = pair.get("effective") or {}
+    defaults = {"auto_goal": "quality", "max_wait_s": 120,
+                "quality_alternatives": "auto"}
+    rows = []
+    for key in keys:
+        if own.get(key) is not None:
+            value, origin = effective.get(key, own[key]), "model override"
+        elif blanket.get(key) is not None:
+            value, origin = effective.get(key, blanket[key]), "box default"
+        elif effective.get(key) is not None:
+            value, origin = effective[key], "reported effective"
+        elif key in defaults:
+            value, origin = defaults[key], "installed-version default"
+        else:
+            value, origin = "Auto / not explicitly set", "runtime rule"
+        rows.append(f"{key}: {format_value(value)}  [{origin}]")
+    return rows
+
+
+def format_value(value):
+    return json.dumps(value, ensure_ascii=False, sort_keys=True) if not isinstance(value, str) else value
+
+
+def size(value):
+    import math
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value) or value < 0:
+        return 'unknown'
+    return f'{value / 2**30:.1f} GiB' if value >= 2**30 else f'{value / 2**20:.0f} MiB' 
+
+
+def sections(data):
+    health, runtime = data.get("health") or {}, data.get("runtime") or {}
+    pair, box, storage = data.get("pair") or {}, data.get("box") or {}, data.get("storage") or {}
+    access, database = runtime.get("access") or {}, runtime.get("database") or {}
+    keys = data.get("keys", {}).get("keys") or []
+    revoked = [key for key in keys if key.get("revoked_at")]
+    connections = [
+        "Wrapper endpoint: " + data["endpoint"],
+        "Core endpoint: " + str(runtime.get("core_endpoint") or health.get("fleet_url") or "not configured / not reported"),
+        "Central endpoint: " + str(runtime.get("central_endpoint") or "not configured / not reported"),
+        "Fleet endpoint: " + str(runtime.get("fleet_endpoint") or "not configured / not reported"),
+        "Database backend: " + str(database.get("engine") or "not reported"),
+        "Database file: " + str(database.get("file") or "not reported / not applicable"),
+        "Database network endpoint: " + str(database.get("network_endpoint") or "none reported"),
+        "Connection report source: " + data.get("runtime_source", "not available"),
+        "Connection report captured: " + str(runtime.get("captured_at") or "not reported"),
+        "", "ACCESS",
+        "Client api_key: " + data["client_api_key"]["display"],
+        "Server api_key: " + str((access.get("server_api_key") or {}).get("display") or "not reported"),
+        "API-key requirement: " + str(access.get("require_key") or "not reported"),
+        "Trusted networks: " + format_value(access.get("trusted_networks", "not reported")),
+        "Trusted proxies: " + format_value(access.get("trusted_proxies", "not reported")),
+        "Caller blacklist: " + str((access.get("caller_blacklist") or {}).get("note") or "not reported"),
+        "Revoked API keys: " + (str(len(revoked)) if "keys" not in data["errors"] else "not available"),
+    ]
+    for key in keys:
+        state = "revoked" if key.get("revoked_at") else "not revoked"
+        connections.append(f"  {key.get('name') or key.get('id')}: scope {key.get('scope')} | {state} | expires {key.get('expires_at')}")
+    if data["errors"]:
+        connections += ["", "UNAVAILABLE FIELDS"] + [f"{name}: {error}" for name, error in data["errors"].items()]
+
+    auto = ["Auto goal ranks permitted placements; tolerance controls their eligibility.",
+            "Defaults below come from this installed Wrapper version when not reported by the API.", ""]
+    if "box" in data["errors"] or "pair" in data["errors"]:
+        auto.append("Settings could not be fully read; effective values are unavailable.")
+    else:
+        auto += knob_rows(data, AUTO_KEYS)
+    auto += ["", "BOX-ONLY SETTINGS"] + [f"{key}: {format_value(value)}" for key, value in sorted((box.get("box_only") or {}).items())]
+
+    model = ["Selected model: " + str(data.get("model") or "none")]
+    if data.get("model") and "pair" not in data["errors"]:
+        all_keys = set(MODEL_KEYS) | set(pair.get("settings") or {}) | set(pair.get("box") or {}) | set(pair.get("effective") or {})
+        model += knob_rows(data, sorted(all_keys))
+        model += ["", "Environment profile: " + format_value(pair.get("env_profile")),
+                  "Quant fallback ceiling: " + format_value(pair.get("quant_fallback"))]
+    else:
+        model.append(data["errors"].get("pair", "Select a model to inspect its own and inherited knobs."))
+
+    worker = ["Worker: " + str(health.get("worker") or "not reported"),
+              "Status: " + str(health.get("status") or "not reported"),
+              "Version: " + str(health.get("version") or "not reported"),
+              "Listen host: " + str(runtime.get("listen_host") or "not reported"),
+              "Listen port: " + str(runtime.get("listen_port") or "not reported"),
+              "", "RESOURCE LIMITS AND TIERS"] + json.dumps(data.get("limits") or {}, indent=2).splitlines()
+
+    central = ["Core connection: " + str(runtime.get("core_endpoint") or health.get("fleet_url") or "not configured / not reported"),
+               "Central connection: " + str(runtime.get("central_endpoint") or "not configured / not reported"),
+               "Reported by this Wrapper; remote Core database settings are separate.", "", "CENTRAL LIBRARY DRIVES"]
+    central += [drive.get("path", "not reported") for drive in storage.get("central_drives", [])] or ["None reported"]
+
+    drives = ["Read-only source = immutable to Wrapper; its source files are not changed.",
+              "Central library holds shared originals. Worker storage holds local working copies.", ""]
+    all_drives = storage.get("drives", []) + storage.get("central_drives", [])
+    if not all_drives:
+        drives.append(data["errors"].get("storage", "No drives reported"))
+    for drive in all_drives:
+        tier = drive.get("tier") or {}
+        drives += [ROLE_LABELS.get(drive.get("role"), drive.get("role") or "Unclassified") + ": " + drive.get("path", "unknown"),
+                   f"  role source: {drive.get('source')} | readable: {drive.get('readable')} | writable by Wrapper: {drive.get('writable')}",
+                   f"  filesystem: {size(drive.get('total'))} | free: {size(drive.get('free'))} | held: {size(drive.get('held'))}",
+                   f"  effective budget: {size(tier.get('effective'))} | room: {size(drive.get('room'))}",
+                   "  mount: " + str(drive.get("mount") or "not reported"), ""]
+    drives.append("TRANSFER SETTINGS")
+    for key, value in (storage.get("switches") or {}).items():
+        drives.append(f"{key}: {format_value(value)}")
+    return [("Connections", connections), ("Auto", auto), ("Model", model),
+            ("Worker", worker), ("Central", central), ("Drives", drives)]
+
+
+def _screen(screen, data, editor=None, drain=None):
+    with settings_input(screen):
+        return _settings_screen(screen, data, editor, drain)
+
+
+def _settings_screen(screen, data, editor=None, drain=None):
+    import curses
+    screen.keypad(True)
+    if editor:
+        editor.screen = screen
+    try:
+        curses.curs_set(0)
+    except curses.error:
+        pass
+    tab, offset = (getattr(editor, 'tab', 0), getattr(editor, 'offset', 0)) if editor else (0, 0)
+    report = getattr(editor, 'report', False)
+    cursors = dict(getattr(editor, 'cursors', {}))
+    pages = sections(data)
+
+    def remember():
+        if editor:
+            editor.tab, editor.offset, editor.report = tab, offset, report
+            editor.cursors = dict(cursors)
+
+    while True:
+        height, width = screen.getmaxyx()
+        screen.erase()
+
+        def put(y, text, attr=0):
+            if 0 <= y < height and width > 1:
+                clean = ''.join(c if c.isprintable() else ' ' for c in str(text))
+                try:
+                    screen.addnstr(y, 0, clean, width - 1, attr)
+                except curses.error:
+                    pass
+
+        section = pages[tab][0]
+        fields = editor.fields(section, data) if editor else []
+        selecting = bool(fields) and not report
+        put(0, 'WRAPPER SETTINGS' + (' — Up/Down select, Enter edit' if selecting else ' — details'), curses.A_BOLD)
+        put(1, ' | '.join(('[' + title + ']') if i == tab else title for i, (title, _) in enumerate(pages)))
+        if selecting:
+            cursor = max(0, min(cursors.get(tab, 0), len(fields) - 1))
+            cursors[tab] = cursor
+            count = max(1, height - 9)
+            start = cursor // count * count
+            for y, (spec, value) in enumerate(fields[start:start + count], 3):
+                active = start + y - 3 == cursor
+                label = spec['label'] + ': ' + (format_value(value) if value is not None else 'inherit')
+                if spec.get('type') in ('bool', 'select', 'model', 'quant'):
+                    label += ' [v]'
+                put(y, ('> ' if active else '  ') + label, curses.A_REVERSE if active else 0)
+            spec, value = fields[cursor]
+            put(height - 5, str(cursor + 1) + '/' + str(len(fields)) + ' · ' + spec['label'], curses.A_BOLD)
+            help_text = spec.get('help') or 'Enter edits this setting; choose inherit to remove an override.'
+            for y, line in enumerate(textwrap.wrap(help_text, max(1, width - 1))[:3], height - 4):
+                put(y, line)
+            footer = 'Click/Up/Down | Enter edit | Tab section | I details | F5 refresh | Esc back'
+        else:
+            lines = []
+            for line in pages[tab][1]:
+                lines += textwrap.wrap(line, max(1, width - 2), replace_whitespace=True) or ['']
+            count = max(1, height - 5)
+            offset = max(0, min(offset, len(lines) - count))
+            for y, line in enumerate(lines[offset:offset + count], 3):
+                put(y, line)
+            footer = 'Up/Down scroll | Tab section | I settings | F5 refresh | Esc back' if fields else 'Up/Down scroll | Tab section | F5 refresh | Esc back'
+        put(height - 1, footer)
+        screen.refresh()
+        key = screen.getch()
+        if drain:
+            drain()
+        if key == curses.KEY_MOUSE:
+            event = mouse_event(screen)
+            if not event:
+                continue
+            if event['wheel']:
+                key = curses.KEY_UP if event['wheel'] < 0 else curses.KEY_DOWN
+            elif event['click'] and event['y'] == 1:
+                x = 0
+                for i, (name, _) in enumerate(pages):
+                    length = len(name) + (2 if i == tab else 0)
+                    if x <= event['x'] < x + length:
+                        tab, offset, report = i, 0, False
+                        break
+                    x += length + 3
+                continue
+            elif event['click'] and selecting and 3 <= event['y'] < 3 + min(count, len(fields) - start):
+                cursors[tab] = start + event['y'] - 3
+                key = 10
+            else:
+                continue
+        if key in (27, curses.KEY_F10, 3, 4):
+            remember()
+            return 'close'
+        if key in (curses.KEY_F5, 18):
+            remember()
+            return 'refresh'
+        if editor and key in (10, 13, curses.KEY_ENTER, ord('e'), ord('E')) and height >= 10 and width >= 30:
+            remember()
+            editor.anchor = 3 + cursors[tab] - start if selecting else 3
+            if editor.edit(section, data, selected=cursors[tab] if selecting else None):
+                return 'refresh'
+            # Cancelled editors have no server changes to reload. Redraw in place.
+            continue
+        if fields and key in (ord('i'), ord('I')):
+            report, offset = not report, 0
+        elif key in (9, curses.KEY_RIGHT, curses.KEY_LEFT, curses.KEY_BTAB):
+            tab = (tab + (-1 if key in (curses.KEY_LEFT, curses.KEY_BTAB) else 1)) % len(pages)
+            offset, report = 0, False
+        elif selecting:
+            if key == curses.KEY_UP:
+                cursors[tab] = max(0, cursor - 1)
+            elif key == curses.KEY_DOWN:
+                cursors[tab] = min(len(fields) - 1, cursor + 1)
+            elif key == curses.KEY_PPAGE:
+                cursors[tab] = max(0, cursor - count)
+            elif key == curses.KEY_NPAGE:
+                cursors[tab] = min(len(fields) - 1, cursor + count)
+            elif key == curses.KEY_HOME:
+                cursors[tab] = 0
+            elif key == curses.KEY_END:
+                cursors[tab] = len(fields) - 1
+        elif key == curses.KEY_UP:
+            offset -= 1
+        elif key == curses.KEY_DOWN:
+            offset += 1
+        elif key == curses.KEY_PPAGE:
+            offset -= count
+        elif key == curses.KEY_NPAGE:
+            offset += count
+        elif key == curses.KEY_HOME:
+            offset = 0
+        elif key == curses.KEY_END:
+            offset = len(lines)
+
+
+def run_settings(screen, gateway, base, model=None, timeout=30, drain=None, wait=None):
+    base = base.rstrip('/')
+    if base.endswith('/v1'):
+        base = base[:-3]
+    editor = SettingsEditor(screen, gateway, base, model, timeout, drain=drain, wait=wait)
+    while True:
+        read = lambda: snapshot(gateway, base, model, timeout)
+        data = wait('Reading Wrapper settings', read) if wait else read()
+        if _screen(screen, data, editor=editor, drain=drain) != 'refresh':
+            return 0
+
+
+def show_settings(gateway, base, model=None, timeout=30, as_json=False):
+    base = base.rstrip('/')
+    if base.endswith('/v1'):
+        base = base[:-3]
+    editor = SettingsEditor(None, gateway, base, model, timeout)
+    while True:
+        data = snapshot(gateway, base, model, timeout)
+        if as_json:
+            print(json.dumps(data, indent=2, ensure_ascii=False))
+            return 1 if data["errors"] else 0
+        if not sys.stdin.isatty() or not sys.stdout.isatty():
+            for title, lines in sections(data):
+                print("\n" + title.upper() + " — READ ONLY")
+                print("\n".join(lines))
+            return 1 if data["errors"] else 0
+        try:
+            import curses
+        except ImportError as exc:
+            print("Settings viewer unavailable: " + str(exc), file=sys.stderr)
+            return 1
+        try:
+            action = curses.wrapper(_screen, data, editor)
+        except curses.error as exc:
+            print("Settings viewer unavailable: " + str(exc), file=sys.stderr)
+            return 1
+        if action != "refresh":
+            return 0

hugpy_settings-0.1.0/src/hugpy_settings/settings_widgets.py

@@ -0,0 +1,241 @@
+"""Small terminal dropdowns, mouse input and a Wrapper-host folder picker."""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+try:
+    import curses
+except ImportError:
+    curses = None
+
+CANCEL = object()
+
+
+def mouse_event(screen):
+    forwarded = getattr(screen, 'settings_mouse_event', None)
+    if forwarded is not None:
+        screen.settings_mouse_event = None
+        return forwarded
+    try:
+        _, x, y, _, state = curses.getmouse()
+        wheel = -1 if state & getattr(curses, 'BUTTON4_PRESSED', 0) else 1 if state & getattr(curses, 'BUTTON5_PRESSED', 0) else 0
+        click = bool(state & (curses.BUTTON1_CLICKED | curses.BUTTON1_PRESSED | curses.BUTTON1_DOUBLE_CLICKED))
+        return {'x': x, 'y': y, 'wheel': wheel, 'click': click}
+    except curses.error:
+        return None
+
+
+def read_directory(gateway, base, path, timeout, offset=0, query='', hidden=False):
+    params = urllib.parse.urlencode({'path': path, 'offset': offset, 'q': query, 'hidden': int(hidden)})
+    headers = {'Accept': 'application/json'}
+    if getattr(gateway, 'api_key', ''):
+        headers['Authorization'] = 'Bearer ' + gateway.api_key
+    request = urllib.request.Request(base + '/v1/drives/browse?' + params, headers=headers)
+    class NoRedirect(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, *a, **kw): return None
+    try:
+        with urllib.request.build_opener(NoRedirect).open(request, timeout=min(timeout, 10)) as response:
+            doc = json.load(response)
+    except urllib.error.HTTPError as exc:
+        try:
+            error = json.loads(exc.read()).get('error', {})
+            detail = error.get('message') if isinstance(error, dict) else str(error)
+        except (ValueError, OSError):
+            detail = ''
+        if exc.code == 404 and detail in ('', 'not found', 'no such route'):
+            detail = 'This running Wrapper does not support folder browsing yet. Update/restart it, or enter a path.'
+        raise ValueError('HTTP %s: %s' % (exc.code, detail or exc.reason)) from None
+    if not isinstance(doc, dict) or not isinstance(doc.get('path'), str) or not isinstance(doc.get('directories'), list):
+        raise ValueError('The running Wrapper does not provide a directory browser. Enter a path or update it.')
+    return doc
+
+
+class SettingsWidgets:
+    def dropdown(self, title, labels, selected=0):
+        """Overlay a choice list on the current settings page."""
+        if self.screen is None:
+            return self.choose(title, labels, selected)
+        h, w = self.screen.getmaxyx()
+        if h < 10 or w < 30:
+            return None
+        selected = max(0, min(selected, len(labels) - 1))
+        size_h = min(h - 2, max(6, len(labels) + 4))
+        size_w = min(w - 2, max(36, len(title) + 6, max(map(len, labels), default=0) + 6))
+        top = max(0, min(getattr(self, 'anchor', 3) + 1, h - size_h - 1))
+        left = max(0, min(2, w - size_w))
+        popup = curses.newwin(size_h, size_w, top, left)
+        count = size_h - 4
+        try:
+            while True:
+                popup.erase()
+                popup.box()
+                popup.addnstr(0, 2, ' ' + title + ' ', size_w - 4, curses.A_BOLD)
+                start = selected // count * count
+                for line, label in enumerate(labels[start:start + count], 2):
+                    i = start + line - 2
+                    popup.addnstr(line, 2, ('> ' if i == selected else '  ') + label, size_w - 4,
+                                  curses.A_REVERSE if i == selected else 0)
+                popup.addnstr(size_h - 2, 2, 'Enter choose | Esc cancel', size_w - 4)
+                popup.refresh()
+                key = self.key()
+                if key in (27, curses.KEY_F10, 3, 4, curses.KEY_RESIZE): return None
+                if key in (10, 13, curses.KEY_ENTER): return selected
+                if key == curses.KEY_UP: selected = max(0, selected - 1)
+                elif key == curses.KEY_DOWN: selected = min(len(labels) - 1, selected + 1)
+                elif key == curses.KEY_HOME: selected = 0
+                elif key == curses.KEY_END: selected = len(labels) - 1
+                elif key == curses.KEY_PPAGE: selected = max(0, selected - count)
+                elif key == curses.KEY_NPAGE: selected = min(len(labels) - 1, selected + count)
+                elif key == curses.KEY_MOUSE:
+                    event = mouse_event(self.screen)
+                    if not event: continue
+                    if event['wheel']:
+                        selected = max(0, min(len(labels) - 1, selected + event['wheel']))
+                    elif event['click']:
+                        row = event['y'] - top - 2
+                        if left <= event['x'] < left + size_w and 0 <= row < min(count, len(labels) - start):
+                            return start + row
+                        return None
+        finally:
+            del popup
+            self.screen.touchwin()
+            self.screen.noutrefresh()
+
+    def browse_directory(self, data):
+        """Browse only the server's filesystem. Never infer a remote path locally."""
+        path, offset, query, hidden = '/', 0, '', False
+        doc = None
+        disks = True
+        selected = 0
+        while True:
+            try:
+                doc = self.fetch('Reading directories on the Wrapper host',
+                                 lambda: read_directory(self.gateway, self.base, path, self.timeout, offset, query, hidden))
+            except (OSError, ValueError) as exc:
+                self.message('Cannot browse that directory', str(exc))
+                return CANCEL
+            path = doc['path']
+            if disks:
+                places = {row['path']: row for row in doc.get('locations', []) if row.get('path')}
+                storage = data.get('storage') or {}
+                for row in storage.get('drives', []) + storage.get('central_drives', []):
+                    if row.get('path'):
+                        places[row['path']] = {**places.get(row['path'], {}), **row}
+                places = sorted(places.values(), key=lambda row: row['path'].casefold())
+                labels = [row['path'] + (' · ' + str(row.get('filesystem') or row.get('role')) if row.get('filesystem') or row.get('role') else '') for row in places]
+                pick = self.choose('Disks and locations on the Wrapper host', labels + ['Enter a directory path'])
+                if pick is None: return CANCEL
+                if pick == len(places):
+                    value = self.text('Directory on the Wrapper host', path, 'Absolute path; Esc cancels')
+                    if value is CANCEL: return CANCEL
+                    path = value
+                else:
+                    path = places[pick]['path']
+                offset, query, disks, selected = 0, '', False, 0
+                continue
+            actions = [('Use this directory', 'select', path), ('.. Parent directory', 'parent', doc['parent']),
+                       ('Disks and locations…', 'disks', None)]
+            if offset:
+                actions.append(('Previous page', 'page', max(0, offset - doc.get('limit', 200))))
+            if doc.get('more'):
+                actions.append(('Next page', 'page', offset + doc.get('limit', 200)))
+            rows = actions + [('[link] ' + row['name'] + '/' if row.get('symlink') else '[dir] ' + row['name'] + '/', 'folder', row['path'])
+                              for row in doc['directories']]
+            selected = min(selected, len(rows) - 1)
+            reload = False
+            while not reload:
+                self.screen.erase()
+                h, w = self.screen.getmaxyx()
+                self.put(0, 'DIRECTORY PICKER · Wrapper host', curses.A_BOLD)
+                self.put(1, self.base)
+                self.put(2, path)
+                free = doc.get('free_bytes')
+                self.put(3, ('Free: %.1f GiB · ' % (free / 2**30) if isinstance(free, (int, float)) else '') +
+                         'Search: ' + (query or 'all folders') + (' · hidden shown' if hidden else '') +
+                         (' · listing capped; narrow search' if doc.get('partial') else ''))
+                count = max(1, h - 8)
+                start = selected // count * count
+                for y, row in enumerate(rows[start:start + count], 5):
+                    active = start + y - 5 == selected
+                    self.put(y, ('> ' if active else '  ') + row[0], curses.A_REVERSE if active else 0)
+                self.put(h - 2, 'Enter open/choose | Space use directory | Left parent | D disks')
+                self.put(h - 1, '/ search | G path | H hidden | F5 refresh | Esc cancel')
+                self.screen.refresh()
+                key = self.key()
+                activate = key in (10, 13, curses.KEY_ENTER, curses.KEY_RIGHT)
+                if key in (27, curses.KEY_F10, 3, 4): return CANCEL
+                if key == curses.KEY_MOUSE:
+                    event = mouse_event(self.screen)
+                    if not event: continue
+                    if event['wheel']:
+                        selected = max(0, min(len(rows) - 1, selected + event['wheel']))
+                    elif event['click'] and 5 <= event['y'] < 5 + min(count, len(rows) - start):
+                        selected, activate = start + event['y'] - 5, True
+                if h < 10 or w < 30:
+                    continue
+                if key == ord(' '): return path
+                if key in (curses.KEY_LEFT, curses.KEY_BACKSPACE, 127, 8):
+                    path, offset, query, selected, reload = doc['parent'], 0, '', 0, True
+                elif key in (ord('d'), ord('D')):
+                    disks, reload = True, True
+                elif key in (ord('g'), ord('G'), ord('/')):
+                    value = self.text('Search folders' if key == ord('/') else 'Directory on the Wrapper host',
+                                      query if key == ord('/') else path,
+                                      'Empty clears search; Ctrl-U clears; Esc cancels' if key == ord('/') else
+                                      'Absolute folder path; Ctrl-U clears; Esc cancels')
+                    if value is not CANCEL:
+                        if key == ord('/'): query = value
+                        else: path = value
+                        offset, selected, reload = 0, 0, True
+                elif key in (ord('h'), ord('H')):
+                    hidden, offset, reload = not hidden, 0, True
+                elif key == curses.KEY_F5:
+                    reload = True
+                elif activate:
+                    _, action, value = rows[selected]
+                    if action == 'select': return path
+                    if action == 'disks': disks = True
+                    elif action == 'page': offset = value
+                    else: path, offset, query = value, 0, ''
+                    selected, reload = 0, True
+                elif key == curses.KEY_UP: selected = max(0, selected - 1)
+                elif key == curses.KEY_DOWN: selected = min(len(rows) - 1, selected + 1)
+                elif key == curses.KEY_PPAGE: selected = max(0, selected - count)
+                elif key == curses.KEY_NPAGE: selected = min(len(rows) - 1, selected + count)
+                elif key == curses.KEY_HOME: selected = 0
+                elif key == curses.KEY_END: selected = len(rows) - 1
+
+
+from contextlib import contextmanager
+
+
+@contextmanager
+def settings_input(screen):
+    """Keep Harness's mouse adapter and curses event mask scoped to settings."""
+    previous = getattr(screen, 'settings_mouse', False)
+    forwarding = False
+    try:
+        screen.settings_mouse = True
+        forwarding = True
+    except AttributeError:  # Native curses windows do not allow custom attributes.
+        pass
+    oldmask = oldinterval = None
+    try:
+        try:
+            _, oldmask = curses.mousemask(curses.BUTTON1_PRESSED | curses.BUTTON1_CLICKED |
+                                          curses.BUTTON1_DOUBLE_CLICKED | curses.BUTTON4_PRESSED |
+                                          getattr(curses, 'BUTTON5_PRESSED', 0))
+            oldinterval = curses.mouseinterval(0)
+        except curses.error:
+            pass
+        yield
+    finally:
+        if forwarding:
+            screen.settings_mouse = previous
+        if oldmask is not None:
+            curses.mousemask(oldmask)
+        if oldinterval is not None:
+            curses.mouseinterval(oldinterval)

hugpy_settings-0.1.0/src/hugpy_settings.egg-info/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: hugpy-settings
+Version: 0.1.0
+Summary: Shared HTTP-backed settings editor and reports for Hugpy Wrapper and Harness
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 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 uses only the Python standard library 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.
+
+```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.
+- `settings_schema`: model and box field descriptions.
+- `settings_controls`: parsing, HTTP updates, and editing workflows.
+- `settings_widgets`: dropdowns, mouse handling, and remote directory browsing.
+
+Wrapper's `fitevict.cli.settings_*` and Harness's
+`hugpy_harness.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-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.0` through it.

hugpy_settings-0.1.0/src/hugpy_settings.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/hugpy_settings/__init__.py
+src/hugpy_settings/settings_controls.py
+src/hugpy_settings/settings_schema.py
+src/hugpy_settings/settings_view.py
+src/hugpy_settings/settings_widgets.py
+src/hugpy_settings.egg-info/PKG-INFO
+src/hugpy_settings.egg-info/SOURCES.txt
+src/hugpy_settings.egg-info/dependency_links.txt
+src/hugpy_settings.egg-info/top_level.txt

hugpy_settings-0.1.0/src/hugpy_settings.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hugpy_settings-0.1.0/src/hugpy_settings.egg-info/top_level.txt

@@ -0,0 +1 @@
+hugpy_settings