# Hermes Relay v3.3

Snelle Quart-bridge tussen Node-RED en een warme Hermes Agent.

```text
Node-RED ──POST /ask──▶ Quart relay ──serialized call──▶ warme Hermes-agent
                           │
                           └── JSON direct terug naar Node-RED

Optioneel: Telegram-bezorging via `hermes send` (standaard uit)
```

## Gedrag en grenzen

- **Warme agent:** Hermes wordt tijdens startup geladen/geïnitialiseerd.
- **Veilige concurrency:** de gedeelde, mutable agent verwerkt precies één LLM-call tegelijk. Overige HTTP-verzoeken wachten in de queue; ze kunnen niet elkaars `messages` resetten.
- **Timeout:** `HERMES_RELAY_TIMEOUT` (standaard 120 s) omvat wachttijd plus LLM-call. Een timeout retourneert HTTP `504`.
- **Snelle response:** Een succesvolle `/ask` reageert zodra het model antwoordt.
- **Geen chatbezorging standaard:** relay-antwoorden blijven in de HTTP-response en verschijnen dus niet in Telegram.
- **Optionele Telegram-bezorging:** alleen met `HERMES_RELAY_TELEGRAM_DELIVERY_ENABLED=true` wordt het antwoord asynchroon via `hermes send` bezorgd. Bij een gecontroleerde shutdown wacht de service op lopende bezorgingen.

## Endpoints

### `POST /ask`

JSON body:

```json
{ "payload": "Wat is het weer in Best?" }
```

Succesresponse:

```json
{
  "status": "ok",
  "answer": "...",
  "elapsed_seconds": 6.213,
  "llm_elapsed_seconds": 6.213,
  "request_elapsed_seconds": 6.214,
  "telegram_queued": false
}
```

`elapsed_seconds` blijft aanwezig voor compatibiliteit en is de LLM-duur. `request_elapsed_seconds` is de feitelijke HTTP-duur. `telegram_queued` is standaard `false`; bij expliciet ingeschakelde Telegram-bezorging betekent `true` dat de achtergrondtaak is ingepland. Raadpleeg dan journald voor het uiteindelijke bezorgresultaat.

Fouten: `400` lege payload, `413` payload groter dan limiet, `504` timeout, `502` onverwachte agentfout.

### `GET /health`

Geeft service-status, versie en het aantal lopende Telegram-bezorgingen terug.

- `/health?detail=true` voegt de **lokale agent-state** toe; dit doet bewust geen dure LLM/provider-call.

## Configuratie

| Variabele | Standaard | Betekenis |
|---|---:|---|
| `HERMES_RELAY_TIMEOUT` | `120` | Max. wachttijd + modelcall per HTTP-request |
| `HERMES_RELAY_TELEGRAM_DELIVERY_ENABLED` | `false` | Zet alleen op `true` voor asynchrone Telegram-bezorging |
| `HERMES_RELAY_DELIVERY_WORKERS` | `2` | Begrensde workers voor Telegram-bezorging als die is ingeschakeld |
| `HERMES_RELAY_MAX_PAYLOAD_CHARS` | `12000` | Maximale lengte van `payload` |
| `HERMES_RELAY_MAX_TURNS` | `10` | Agent turn-budget |
| `HERMES_RELAY_MODEL` | profieldefault | Optionele modelovertuiging |
| `HERMES_RELAY_TOOLSETS` | leeg | Alleen invullen met geldige benodigde toolsets |

De relay leest zijn Hermes-config via profiel `voice-assistant`. Pas model/provider/config aan en herstart daarna de service:

```bash
systemctl restart hermes-relay
```

## Testen

```bash
curl -s http://127.0.0.1:8650/health
curl -s -X POST http://127.0.0.1:8650/ask \
  -H 'Content-Type: application/json' \
  -d '{"payload":"Zeg alleen hoi"}'

journalctl -u hermes-relay -f
```

## Node-RED

Gebruik een HTTP Request-node:

- **Method:** `POST`
- **URL:** `http://192.168.1.74:8650/ask`
- **Return:** parsed JSON
- **Timeout:** `120000` ms

Voorafgaande Function-node:

```javascript
msg.payload = { payload: msg.payload };
return msg;
```