Metadata-Version: 2.4
Name: hugpy-fleet
Version: 0.2.11
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.1.10

# 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 a terminal counterpart of the web
console's GPU Workers component: worker cards with version/admission status,
GPU/RAM/CPU/storage resources and allocation counts. Select a card and Enter to
expand its model allocations. Tab switches worker. B opens shared worker
settings, D drive details, G resource/process details, O worker actions, H the
Wrapper Harness, L adds a model allocation, K edits model settings, P toggles a
pin and Enter opens allocation/stage/free actions. Escape collapses the table,
then returns to chat. Q returns directly to chat. Actions use Core's existing
allocation and Wrapper-confirmed settings paths.

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


## Fleet terminal compatibility release — 2026-10-22

Includes the interactive GPU Workers console, multi-select + Model allocation table, opaque popup rendering, and the resource Wrapper selector. Auto-route is checked by default and sends general fleet calls; unchecking it restricts routing to the highlighted Worker batch. Selection and mode persist per session. Explicit Wrapper selection targets that Wrapper.
