Ty_Tech/Salon_Assistant
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement install stages S0–S2: bootstrap, env, model and vision smoke.

Browse Source 
Operator can run make bootstrap/install through S2 using nemohermes/openshell wrappers; docs and implement queue updated. No S3+ and no push.
This commit is contained in:
Ty
2026-07-27 11:47:34 -07:00
parent 998e32e871
commit e5e179e541
14 changed files with 893 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOYER_HOST.md
+37 -11
View File
@@ -1,29 +1,55 @@
# Deployer host baselining
**Status:** Outline from approved design POR. Procedural scripts at **build**.
**Status:** Procedural — ready for operator use.
## Purpose
Create a clean host that can run the Docker-based Lumina stack. This product is **repo-driven**, not tied to one developer’s existing Hermes install.
Create a clean host that can run the Docker-based Lumina stack. This product is **repo-driven**, not tied to one developer's existing Hermes install.
## Requirements (POR)
## Requirements
| Item | Spec |
|------|------|
| OS | Linux x86_64 or arm64 (cloud VM, bare metal; WSL2 optional path only) |
| Resources | Multi-core CPU; ≥8–16 GB RAM recommended; disk for Docker images |
| Privileges | User able to install Docker / run Compose |
| Privileges | User able to install Docker / run Compose (sudo access) |
| Network | Outbound HTTPS to model endpoint, SaaS APIs, MCP remotes, image registry |
| GPU | Optional; only if local VLM is used (not required if vision is remote) |
## Steps (operator)
## Prerequisites (before running scripts)
1. Provision host (cloud console / hypervisor).
2. Install base OS updates.
3. Create deploy user; clone this repository.
4. Run `./scripts/bootstrap.sh` (installs Docker if missing — when implemented).
5. Continue with [INSTALL.md](INSTALL.md).
1. **Provision host** — cloud console, hypervisor, or bare metal.
2. **Install base OS updates** — `sudo apt update && sudo apt upgrade -y` (Debian/Ubuntu) or equivalent.
3. **Create deploy user** — a non-root user with sudo access.
4. **Install NemoClaw CLIs** — `nemohermes` and `openshell` must be on PATH. See [NemoClaw docs](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/reference/architecture.md) for installation.
5. **Clone this repository** — `git clone <repo-url> && cd Salon_Assistant`.
## Bootstrap (S0b)
Run the bootstrap script to install Docker if missing:
```bash
./scripts/bootstrap.sh
```
Or via Make:
```bash
make bootstrap
```
**What it does:**
- Detects if Docker is already installed and running (idempotent).
- If missing, installs Docker via the official convenience script (Debian/Ubuntu) or dnf (RHEL/Fedora).
- Adds the current user to the `docker` group.
- Verifies the Docker daemon is reachable.
**If Docker is already present:** the script detects it and exits immediately with a success message.
## Continue with install
After bootstrap, proceed to [INSTALL.md](INSTALL.md) for stages S1–S2.
## Design reference
[design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md) § Docker packaging and install stages.
[design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md) §4 Docker packaging and install stages.
docs/HERMES_MODELS.md
+72 -8
View File
@@ -1,13 +1,77 @@
# Hermes model configuration
**Status:** Outline from approved design.
**Status:** S2-ready — sufficient for operators configuring models.
| Slot | Requirement |
|------|-------------|
| **Main** | OpenAI-compatible chat + tools; endpoint **may be outside Docker** |
| **Auxiliary `vision`** | **Required** for media social; install smoke test |
| **Other aux** | Default to same base/main endpoint unless overridden |
## Model slots
Configured via NemoClaw inference + generated Hermes config (`nemohermes inference set` / sealed config), not owner terminal editing.
| Slot | Requirement | Configured via |
|------|-------------|----------------|
| **Main** | OpenAI-compatible chat + tools; endpoint **may be outside Docker** | `openshell inference set` + `.env` |
| **Auxiliary `vision`** | **Required** for media social; install smoke test | `.env` + vision smoke |
| **Other aux** | Default to same base/main endpoint unless overridden | `.env` |
See [design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md) and [Hermes Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models).
## Environment variables
All model configuration lives in `.env`. See `.env.example` for the template.
| Variable | Purpose | Example |
|----------|---------|---------|
| `LUMINA_INFERENCE_BASE_URL` | OpenAI-compatible endpoint base URL | `http://192.168.1.203:8083/v1` |
| `LUMINA_INFERENCE_MODEL` | Main model identifier (must match what the server advertises) | `/home/ty/models/…/Qwen3.6-27B-UD-Q4_K_XL.gguf` |
| `LUMINA_INFERENCE_API_KEY` | API key for the inference endpoint (empty if unauthenticated) | *(leave empty for local endpoints)* |
| `LUMINA_VISION_MODEL` | Vision-capable model for social media / media understanding | Same as main if multimodal |
| `LUMINA_SANDBOX` | Sandbox name (used by `nemohermes` commands) | `hermes` |
## Configuring the main model
The main model is configured through the OpenShell gateway:
```bash
openshell inference set \
--provider compatible-endpoint \
--model "$LUMINA_INFERENCE_MODEL" \
--no-verify
```
This is done automatically by `scripts/install/s2-models.sh` when the gateway is connected.
**Provider name:** `compatible-endpoint` is the NemoClaw provider for OpenAI-compatible endpoints (llama.cpp, Ollama, vLLM, etc.).
**Note:** `openshell inference set` takes `--provider` and `--model` but **not** `--url`. The gateway resolves the endpoint URL from its own metadata (the compatible-endpoint provider reads the URL from the gateway config). The install script verifies the endpoint is reachable before calling `openshell inference set`.
## Vision model
The vision model must support multimodal inputs (images). The install smoke test verifies this:
1. Probes the models endpoint (`$LUMINA_INFERENCE_BASE_URL/models`) for a `multimodal` capability tag.
2. Falls back to a chat completion probe if tags are not available.
If the main model is already multimodal, set `LUMINA_VISION_MODEL` to the same value as `LUMINA_INFERENCE_MODEL`.
## Checking current configuration
```bash
# See what the gateway has configured
openshell inference get
# See what models the endpoint advertises
curl -s "$LUMINA_INFERENCE_BASE_URL/models" | jq '.models[].name'
# Check sandbox status
nemohermes <sandbox-name> status
```
## Runtime changes
Per NemoClaw's runtime change matrix:
- **Inference route changes** are typically hot (no rebuild needed).
- **Auxiliary model changes** may require a gateway restart.
- Always use `nemohermes` / `openshell` for mutations — never hand-edit in-sandbox config.
See [design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md) §3.4 and [NemoClaw runtime changes docs](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/configure-sandboxes/understand-runtime-changes.md).
## References
- [Hermes Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models)
- [Hermes Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)
- [design/research/platform-notes.md](../design/research/platform-notes.md)
docs/INSTALL.md
+99 -15
View File
@@ -1,31 +1,115 @@
# Install
**Status:** Outline from approved design. Scripts stubbed until **build**.
**Status:** Stages S0–S2 implemented. S3–S7 pending.
## Stages
| Stage | Where | Outcome |
|-------|--------|---------|
| S0 | Human | Host per [DEPLOYER_HOST.md](DEPLOYER_HOST.md) |
| S0b | Host script | Docker installed if missing |
| S1 | Host script | Repo env, `.env` from `.env.example` |
| S2 | Host script | Main + aux vision config; vision smoke |
| S3–S5 | Host → Compose / `nemohermes` | Stack, sandbox, policy, skills |
| S6 | Host script | Doctor green |
| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels |
| Stage | Where | Outcome | Status |
|-------|--------|---------|--------|
| S0 | Human | Host per [DEPLOYER_HOST.md](DEPLOYER_HOST.md) | ✅ Procedural |
| S0b | Host script | Docker installed if missing | ✅ Implemented |
| S1 | Host script | Repo env, `.env` from `.env.example` | ✅ Implemented |
| S2 | Host script | Main + aux vision config; vision smoke | ✅ Implemented |
| S3–S5 | Host → Compose / `nemohermes` | Stack, sandbox, policy, skills | ⏳ Pending |
| S6 | Host script | Doctor green | ⏳ Pending |
| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels | ⏳ Pending |
## Platform commands (normative)
All mutations: `nemohermes` / `openshell` (see [design/research/platform-notes.md](../design/research/platform-notes.md)).
## Intended entrypoints
---
## S0: Host baselining
Follow [DEPLOYER_HOST.md](DEPLOYER_HOST.md) to prepare the host:
1. Provision a Linux host (cloud VM, bare metal).
2. Install OS updates.
3. Create a deploy user with sudo access.
4. Install `nemohermes` and `openshell` CLIs.
5. Clone this repository.
## S0b: Docker bootstrap
```bash
./scripts/bootstrap.sh
./scripts/install.sh
./scripts/doctor.sh
# or
make bootstrap
```
## After install
**Idempotent:** if Docker is already installed and running, the script exits immediately.
[SETUP_UX.md](SETUP_UX.md) · [design/scenarios.md](../design/scenarios.md) (S1–S5).
**What it checks:**
- `docker info` succeeds → skip install.
- OS family detection (Debian/Ubuntu or RHEL/Fedora).
- Installs Docker, adds user to `docker` group, verifies daemon.
## S1: Repository environment
```bash
./scripts/install/s1-env.sh
# or
make install-s1
```
**What it does:**
1. If `.env` does not exist, copies `.env.example` to `.env`.
2. Validates that all required keys are present and non-empty:
- `LUMINA_SANDBOX` — sandbox name (default: `hermes`)
- `LUMINA_INFERENCE_BASE_URL` — inference endpoint URL
- `LUMINA_INFERENCE_MODEL` — model identifier
- `LUMINA_VISION_MODEL` — vision model identifier
3. Fails with clear messages if keys are missing or empty.
**Edit `.env`** with your actual values before running S2. See `.env.example` for all keys and descriptions.
**Never commit `.env` with real secrets.** It is in `.gitignore`.
## S2: Model + vision configuration
```bash
./scripts/install/s2-models.sh
# or
make install-s2
```
**What it does:**
1. Loads `.env` and validates required keys.
2. Checks that `nemohermes` and `openshell` CLIs are available.
3. Verifies the inference endpoint is reachable (`/v1/models`).
4. If the OpenShell gateway is connected, configures the inference route via `openshell inference set`.
5. Runs the **vision smoke test**:
- Probes `/v1/models` for `multimodal` capability tag.
- Falls back to a minimal chat completion if capability tags are not exposed.
6. **Fails loudly** (non-zero exit) if vision capability cannot be confirmed.
**If the gateway is not yet connected:** the script validates the endpoint and skips the `openshell` write. S3+ will handle full gateway configuration.
## Run all stages (S0b–S2)
```bash
./scripts/install.sh
# or
make install
# or
make install-s0-s2
```
## After install (S0–S2)
- Verify `.env` values are correct for your environment.
- Continue with S3+ when implemented (compose stack, sandbox creation, policy, skills).
- See [SETUP_UX.md](SETUP_UX.md) for owner-facing setup after full install.
- See [design/scenarios.md](../design/scenarios.md) (S1–S5) for operational scenarios.
## UAT host notes
This repository was tested on a live host with:
- `nemohermes` v0.0.93, `openshell` v0.0.85
- Sandbox: `hermes` (default)
- Gateway: `nemoclaw` at `https://127.0.0.1:8080`
- Inference: OpenAI-compatible endpoint with multimodal model
- Docker: present and running
Scripts are idempotent on this configuration.