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

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

## Per-worker Compute controls

Fleet mirrors Wrapper model and settings controls through Core, with the
additional Core allocation and pin state kept separate from residency.
`/models [WORKER]` and `/model` use the same model browser as Wrapper Harness,
scoped to a selected worker. Core relays the full Wrapper catalog, preserving
quant artifacts, effective settings, engine, runtime, tasks and storage facts.
F3/F4/F6/F7 use the shared quant, MoE/4-bit, allocation and context editors.
F8 switches worker; F9 opens that model in Core Compute. F2 opens its model
settings. Enter selects the model for chat through Core's normal routing.
`/compute [WORKER]` opens Core allocations, pins and worker controls.
`/settings` opens selected worker defaults; the initial visit asks which worker
to edit. The worker choice is shared while this terminal is open.

The Compute console uses the same Core database inventory and settings routes
as the web Compute UI. It distinguishes saved settings, planned footprints and
measured resident allocations. Worker defaults and per-model patches require
Wrapper readback. Allocation and pin changes require Core readback. Stage/free
requests are labelled submitted and their eventual outcome is observed on
refresh. No model is loaded or request sent by browsing these views.

Keys: W/Tab/Left/Right select worker; B worker defaults (including accepted
drive settings); D drives; O refresh/free/unload worker actions; I selected
model saved/plan/measured detail; K per-model knobs; L add model; Enter model
actions. Existing pin, allocation, residency, quant, context, MoE, 4-bit,
environment and Auto preferences use Core's live schema. A JSON object editor
is available for drive designations/budgets and structured Auto preferences.

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.
