Metadata-Version: 2.4
Name: hugpy-fleet
Version: 0.2.13
Summary: Headless fleet control arm for Hugpy Core with a shared optional terminal
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: hugpy-terminal<0.2,>=0.1.21

# Hugpy Fleet — Core arm

`hugpy-fleet` is the headless fleet console for Hugpy Core. It discovers the
installed Core endpoint without a role prompt or environment variable and
mirrors the same Wrapper-owned knobs exposed by `hugpy-harness`.

`hugpy-harness` controls one Wrapper; `hugpy-fleet` controls the fleet through
Core. Both depend on `hugpy-terminal` and the shared settings contract. Neither
arm depends on the other arm or on a local inference engine. Flask stays at
Core's external API boundary; Core's internal services use its own store and
headless primitives directly.

## Headless use

```sh
hugpy-fleet endpoint
hugpy-fleet status
hugpy-fleet workers
hugpy-fleet models
hugpy-fleet schema --worker ae
hugpy-fleet settings --worker ae
hugpy-fleet settings --worker ae --model MODEL
hugpy-fleet settings --worker ae --model MODEL --set '{"ctx":8192}'
```

Commands return JSON. `--base URL` optionally overrides the address while
retaining Core identity. An unavailable Core does not fall back to a Wrapper.
A `null` setting restores inheritance. Pair reads identify Core's stored mirror;
confirmed writes carry the owning Wrapper's readback.

```python
from hugpy_fleet import Fleet
fleet = Fleet()
print(fleet.workers())
# fleet.settings('ae', model='MODEL', changes={'ctx': 8192})
```

## Interactive and session clients

`hugpy-fleet tui`, `hugpy-fleet chat`, `hugpy-fleet sessions` and
`hugpy-fleet serve` use the shared terminal runtime bound to Core. Core's Station
console launches `hugpy-fleet tui`. The default Fleet journal is
`.hugpy_fleet/chat`; an existing journal can be selected explicitly.

The standalone Debian package bundles the wheels for offline installation into
`/opt/hugpy-fleet/venv`. Core also bundles Fleet in its own runtime. Build with
`installers/debian/build.sh OUTPUT`, then install the explicit `.deb`.

## Fleet models, Wrapper Harness and GPU Workers console

`/models [ENGINE|all]` (also `/model`) displays the complete fleet model catalog,
including all tasks, worker copies and central libraries. Tab cycles the engine
filter and typing searches the table. Enter offers compatible chat/task actions
or opens controls on a chosen Wrapper. Fleet-wide chat selections use normal
Core routing; they clear a prior session-specific Wrapper target.

`/wrappers [WORKER]` (also `/wrapper`) selects a registered Wrapper and mirrors
its Harness model browser and shared settings through Core. Its catalog is
exactly what that Wrapper advertises, including any central library it exposes.
F3/F4/F6/F7 open the shared quant, MoE/4-bit, allocation and context controls.
F8 switches Wrapper; F9 opens its allocation in the GPU Workers console. F2 opens
model settings. Selecting a model here records the selected worker in the
session and sends Core's `alloc.worker` target on subsequent chat calls.

`/console [WORKER]` (also `/compute`) opens the interactive GPU Workers
console. A persistent worker selector sits beside clickable Models, GPU, RAM,
Swap, CPU, Storage, Activity and Settings tabs. Narrow terminals use a compact
worker bar. The action bar exposes settings, + Model, Free VRAM, Free RAM,
refresh and the worker actions menu.

Model cells use the existing Harness dropdowns, checkboxes and context/placement
sliders. Allocated, pin, quant, placement, MoE/4-bit, context, residency and
measured memory columns are selectable with Left/Right; the model name stays
visible while secondary columns scroll. Serving, Allocated, Local and All fleet
filters keep allocation state distinct from model availability.

+ Model (or L) opens the UI-style multi-select allocation table. It shows storage
relative to the chosen worker (hot/shared/central/none), central verification,
Wrapper fit verdicts, every advertised task, engine, serving size, trained context
and other allocations. Search and task/drive/fit filters retain checked models.
Click headers or press S to sort; Left/Right scrolls columns with names fixed.
Space/Enter checks a row; A selects eligible visible rows; F9 or Allocate applies
the checked group. Models allocated elsewhere stay locked until B deliberately
allows duplicates; archived models always stay locked. I shows copy paths and fit
or refusal details. Each assignment uses Core's existing endpoint and readback;
partial failures remain checked with their own reasons. Allocation designates
routing; loading and file placement happen when called. Escape cancels unapplied
selections and returns to the console.

Resource tabs show per-card GPU use, driver/external/Wrapper memory, individual
PIDs, resident model panels, CPU assignments, swap, drive roles/budgets, transfer
switches and request activity. Settings fields edit in place through the shared
menus and limit sliders. Worker actions include refresh, unload, free RAM,
restart, wildcard routing, pools and admission. These are explicit actions;
browsing makes no configuration changes.

Click a control or use Tab to focus workers, tabs, content and the action bar.
[ / ] switches worker. Enter/Space activates the selected control. F2 opens
worker settings, F3 quant, F4 MoE/4-bit, F6 placement, F7 context, F8 the Wrapper
Harness, F5 refresh and F1 navigation help. Escape closes a menu or returns focus
to workers; Q returns directly to chat. Actions use Core's existing allocation
and Wrapper-confirmed settings paths.

The main terminal resource pane has an Auto-route checkbox above highlighted
Wrapper selectors. Auto-route is on by default: requests use general fleet
routing, while Wrapper highlights filter resource visibility. Turn Auto-route
off to restrict inference and task requests to the highlighted Worker batch.
Switching modes preserves the selection. In manual mode the batch contains the
selected Worker IDs; it does not automatically expand when another Worker joins.
Selecting none pauses sending only in manual mode. All toggles the whole view
or manual batch. Choices and routing mode persist per session.

Click a checkbox, or use Ctrl-R, Left/Right and Space; Down enters resource
details and W returns to the selectors. Explicitly selecting a Wrapper model
turns Auto-route off and targets that Wrapper. Core enforces manual selection
before residency, allocation and wildcard ranking. `/observe` remains an
independent observation filter. Direct single-Wrapper sessions retain their
existing target.

`/settings [WORKER]` opens the shared Harness settings editor for the selected
Wrapper, with Connections, Auto, Model, Worker, Central and Drives tabs. The
initial visit asks which Wrapper to edit. The Wrapper choice is shared while
this terminal is open. Escape returns to chat; F2 settings return to their model
browser. All views keep the configured Core endpoint; clients do not connect
directly to the registered loopback Wrapper URLs.

Browsing does not load a model. Settings saves require Wrapper readback;
allocation and pin changes require Core readback. Stage/free requests are
submitted actions whose eventual result is observed on refresh. Measured
residency is distinguished from reported load state in the console table.

Headless equivalents:

```sh
hugpy-fleet compute --worker ae
hugpy-fleet models --worker ae --query Qwen
hugpy-fleet resources --worker ae
hugpy-fleet drives --worker ae
hugpy-fleet detail --worker ae --model MODEL
hugpy-fleet settings --worker ae
hugpy-fleet settings --worker ae --model MODEL
hugpy-fleet action assign --worker ae --model MODEL
```

Actions are explicit mutations; reads do not trigger inference. Shared clients
unwrap Core's standard `result` response envelope before reading inventory or
confirming writes. Worker resource/plan reads carry Core-mirror provenance.
