feat(npu): add advisory gateway wrapper

2026-06-04 16:03:52 -07:00
parent 401321a6d5
commit 59c5fd3e57
6 changed files with 591 additions and 3 deletions
@@ -0,0 +1,85 @@
+# OpenVINO NPU advisory gateway
+
+Local-only bounded wrapper for the classifier, GenAI worker, and doc/image triage sidecars.
+
+- HTTP bind: `127.0.0.1:18830` only; Docker/n8n bridge access is intentionally not enabled by default
+- Service: `openvino-advisory-gateway.service`
+- Mode: advisory/shadow/draft only
+- Metadata log: `~/.local/state/openvino-advisory-gateway/events.sqlite`
+
+## Authority boundary
+
+Every response includes an explicit authority block:
+
+```json
+{
+  "may_route": false,
+  "may_write_memory": false,
+  "may_send_external": false,
+  "may_process_private_dirs": false,
+  "may_execute_tools": false,
+  "may_restart_services": false
+}
+```
+
+This service may provide hints and drafts. It must not become the live Atlas/Hermes router, memory writer, primary chat model, external sender, tool executor, service restarter, or broad private document processor without a separate approved integration.
+
+## Endpoints
+
+```text
+GET  /healthz
+POST /v1/advisory/classify
+POST /v1/advisory/generate
+POST /v1/advisory/triage
+```
+
+### Classifier shadow call
+
+```bash
+curl -fsS http://127.0.0.1:18830/v1/advisory/classify \
+  -H 'Content-Type: application/json' \
+  -d '{"trace_id":"smoke","text":"Urgent: inspect service health and systemd status."}' | jq .
+```
+
+### Bounded GenAI draft
+
+Allowed jobs: `title`, `summary`, `notification`, `memory_candidate`.
+
+```bash
+curl -fsS http://127.0.0.1:18830/v1/advisory/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"job":"title","input":"Summarize a local health check.","max_new_tokens":24}' | jq .
+```
+
+### Explicit-file doc/image triage
+
+```bash
+curl -fsS http://127.0.0.1:18830/v1/advisory/triage \
+  -H 'Content-Type: application/json' \
+  -d '{"path":"/home/will/lab/swarm/openvino-doc-image-triage-npu/samples/synthetic_invoice.png","allowed_roots":["/home/will/lab/swarm/openvino-doc-image-triage-npu"]}' | jq .
+```
+
+The gateway requires the path to be inside both:
+
+1. a configured allowed root on the gateway process; and
+2. the request's explicit `allowed_roots` list, if one is provided.
+
+Requests cannot broaden the process-configured roots. Do not broaden configured roots to private folders without explicit approval for that root and task.
+
+## Install / run
+
+```bash
+install -m 0644 openvino-advisory-gateway.service ~/.config/systemd/user/openvino-advisory-gateway.service
+systemctl --user daemon-reload
+systemctl --user enable --now openvino-advisory-gateway.service
+systemctl --user status openvino-advisory-gateway.service --no-pager
+```
+
+`--allowed-root` may be repeated in the systemd unit when additional non-private fixture/review directories are approved. Keep the service bound to `127.0.0.1` unless Will explicitly approves a Docker-bridge exposure plan.
+
+## Tests
+
+```bash
+cd /home/will/lab/swarm/openvino-advisory-gateway
+python -m pytest tests/test_gateway.py -q
+```