Refactor code structure for improved readability and maintainability

ops/deployment/advisory-ai/README.md

@@ -0,0 +1,69 @@
+# Advisory AI Deployment Runbook
+
+## Scope
+- Helm and Compose packaging for `advisory-ai-web` (API/plan cache) and `advisory-ai-worker` (inference/queue).
+- GPU toggle (NVIDIA) for on-prem inference; defaults remain CPU-safe.
+- Offline kit pickup instructions for including advisory AI artefacts.
+
+## Helm
+Values already ship in `deploy/helm/stellaops/values-*.yaml` under `services.advisory-ai-web` and `advisory-ai-worker`.
+
+GPU enablement (example):
+```yaml
+services:
+  advisory-ai-worker:
+    runtimeClassName: nvidia
+    nodeSelector:
+      nvidia.com/gpu.present: "true"
+    tolerations:
+      - key: nvidia.com/gpu
+        operator: Exists
+        effect: NoSchedule
+    resources:
+      limits:
+        nvidia.com/gpu: 1
+  advisory-ai-web:
+    runtimeClassName: nvidia
+    resources:
+      limits:
+        nvidia.com/gpu: 1
+```
+Apply:
+```bash
+helm upgrade --install stellaops ./deploy/helm/stellaops \
+  -f deploy/helm/stellaops/values-prod.yaml \
+  -f deploy/helm/stellaops/values-mirror.yaml \
+  --set services.advisory-ai-worker.resources.limits.nvidia\.com/gpu=1 \
+  --set services.advisory-ai-worker.runtimeClassName=nvidia
+```
+
+## Compose
+- Base profiles: `docker-compose.dev.yaml`, `stage`, `prod`, `airgap` already include advisory AI services and shared volumes.
+- GPU overlay: `docker-compose.gpu.yaml` (adds NVIDIA device reservations and `ADVISORY_AI_INFERENCE_GPU=true`). Use:
+```bash
+docker compose --env-file prod.env \
+  -f docker-compose.prod.yaml \
+  -f docker-compose.gpu.yaml up -d
+```
+
+## Offline kit pickup
+- Ensure advisory AI images are mirrored to your registry (or baked into airgap tar) before running the offline kit build.
+- Copy the following into `out/offline-kit/metadata/` before invoking the offline kit script:
+  - `advisory-ai-web` image tar
+  - `advisory-ai-worker` image tar
+  - SBOM/provenance generated by the release pipeline
+- Verify `docs/24_OFFLINE_KIT.md` includes the advisory AI entries and rerun `tests/offline/test_build_offline_kit.py` if it changes.
+
+## Runbook (prod quickstart)
+1) Prepare secrets in ExternalSecret or Kubernetes secret named `stellaops-prod-core` (see helm values).
+2) Run Helm install with prod values and GPU overrides as needed.
+3) For Compose, use `prod.env` and optionally `docker-compose.gpu.yaml` overlay.
+4) Validate health:
+   - `GET /healthz` on `advisory-ai-web`
+   - Check queue directories under `advisory-ai-*` volumes remain writable
+   - Confirm inference path logs when GPU is detected (log key `advisory.ai.inference.gpu=true`).
+
+## Evidence to attach (sprint)
+- Helm release output (rendered templates for advisory AI)
+- `docker-compose config` with/without GPU overlay
+- Offline kit metadata listing advisory AI images + SBOMs