> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

# Advisory AI Overview

_Updated: 2025-11-03 • Owner: Docs Guild & Advisory AI Guild • Status: Draft_

Advisory AI is the retrieval-augmented assistant that synthesises Conseiller (advisory) and Excititor (VEX) evidence, Policy Engine context, and SBOM insights into explainable outputs. It operates under the Aggregation-Only Contract (AOC): no derived intelligence alters or mutates raw facts, and every generated recommendation is paired with verifiable provenance.

## 1. Value proposition

- **Summaries on demand** – deterministically produce advisory briefs that highlight impact, exploitability, and mitigation steps with paragraph-level citations.
- **Conflict explainers** – reconcile diverging VEX statements by exposing supplier trust metadata, confidence weights, and precedence logic.
- **Remediation planning** – merge SBOM timelines, dependency paths, and policy thresholds to propose actionable remediation plans tailored to the requesting tenant.
- **Offline parity** – the same workflows execute in air-gapped deployments using local inference profiles; cache artefacts can be exported as DSSE bundles for audits.

## 2. Architectural highlights

| Layer | Responsibilities | Key dependencies |
|-------|------------------|------------------|
| Retrievers | Fetch deterministic advisory/VEX/SBOM context, guardrail inputs, policy digests. | Conseiller, Excititor, SBOM Service, Policy Engine |
| Orchestrator | Builds `AdvisoryTaskPlan` objects (summary/conflict/remediation) with budgets and cache keys. | Deterministic toolset (AIAI-31-003), Authority scopes |
| Guardrails | Enforce redaction, structured prompts, citation validation, injection defence, and DSSE sealing. | Security Guild guardrail library |
| Outputs | Persist cache entries (hash + context manifest), expose via API/CLI/Console, emit telemetry. | Mongo cache store, Export Center, Observability stack |

See `docs/modules/advisory-ai/architecture.md` for deep technical diagrams and sequence flows.

## 3. Guardrails & compliance

1. **Aggregation-only** – only raw facts from authorised sources are consumed; no on-the-fly enrichment beyond deterministic tooling.
2. **Citation-first** – every sentence referencing external evidence must cite a canonical paragraph/statement identifier.
3. **Content filters** – redaction, policy-based profanity filters, and prompt allowlists are applied before model invocation.
4. **Deterministic cache** – outputs are stored with `inputDigest` and `outputHash`; force-refresh regenerates the same output unless upstream evidence changes.
5. **Audit & scope** – Authority scopes (`advisory-ai:view|operate|admin`) plus `aoc:verify` are mandatory; audit events (`advisory_ai.output.generated`, etc.) flow to the Authority ledger.

## 4. Supported personas & surfaces

| Persona | Typical role | Access |
|---------|--------------|--------|
| **Operations engineer** | Reviews summaries/remediation recommendations during incident triage. | Console + `advisory-ai:view` |
| **Platform engineer** | Automates remediation planning via CI/CD or CLI. | CLI + API + `advisory-ai:operate` |
| **Security/Compliance** | Audits guardrail decisions, exports outputs for evidence lockers. | API/Export Center + `advisory-ai:view` |
| **Service owner** | Tunes profiles, remote inference settings, and rate limits. | Authority admin + `advisory-ai:admin` |

Surfaces:
- **Console**: dashboard widgets (pending in CONSOLE-AIAI backlog) render cached summaries and conflicts.
- **CLI**: `stella advise run <task>` (AIAI-31-004C) for automation scripts.
- **API**: `/v1/advisory-ai/*` endpoints documented in `docs/advisory-ai/api.md`.

## 5. Data sources & provenance

- **Advisories** – Conseiller raw observations (CSAF/OSV) with paragraph anchors and supersedes chains.
- **VEX statements** – Excititor VEX observations plus trust weights provided by VEX Lens.
- **SBOM context** – SBOM Service timelines and dependency graphs (requires AIAI-31-002 completion).
- **Policy** – Policy Engine explain traces, waivers, and risk ratings used to contextualise responses.
- **Runtime posture** – Optional Zastava signals (exposure, admission status) when available.

All sources are referenced via content hashes (`content_hash`, `statement_id`, `timeline_entry_id`) ensuring reproducibility.

## 6. Profiles & deployment options

| Profile | Location | Notes |
|---------|----------|-------|
| `default` / `fips-local` | On-prem GPU/CPU | Packaged with Offline Kit; FIPS-approved crypto.
| `gost-local` | Sovereign clusters | GOST-compliant crypto & model pipeline.
| `cloud-openai` | Remote (optional) | Disabled by default; requires tenant consent and policy alignment.
| Custom profiles | Operator-defined | Managed via Authority `advisory-ai` admin APIs and documented policy bundles.

Offline deployments mirror prompts, guardrails, and weights within Offline Kits. Remote profiles must pass through Authority consent enforcement and strict allowlists.

## 7. Observability & SLOs

Metrics (pre-registered in Observability backlog):
- `advisory_ai_requests_total{tenant,task,profile}`
- `advisory_ai_latency_seconds_bucket`
- `advisory_ai_guardrail_blocks_total`
- `advisory_ai_cache_hits_total`

Suggested SLOs (subject to Observability sprint sign-off):
- P95 latency ≤ 3s for local profiles, ≤ 8s for remote profiles.
- Guardrail block rate < 1% (investigate above threshold).
- Cache hit ratio ≥ 60% for repeated advisory requests per tenant.

## 8. Roadmap & dependencies

| Area | Key tasks |
|------|----------|
| API delivery | DOCS-AIAI-31-003 (completed), AIAI-31-004A (service wiring), AIAI-31-006 (public endpoints). |
| Guardrails | AIAI-31-005, Security Guild reviews, DSSE provenance wiring (AIAI-31-004B). |
| CLI & Console | AIAI-31-004C (CLI), CONSOLE-AIAI tasks (dashboards, widgets). |
| Docs | DOCS-AIAI-31-002 (architecture deep-dive), DOCS-AIAI-31-004 (console guide), DOCS-AIAI-31-005 (CLI guide). |

## 9. Checklist

- [ ] SBOM context retriever (AIAI-31-002) completed and tested across ecosystems.
- [ ] Guardrail library integrated and security-reviewed.
- [ ] Authority scopes and consent toggles validated in staging.
- [ ] Telemetry dashboard reviewed with Observability guild.
- [ ] Offline kit bundle includes prompts, guardrail configs, local profile weights.

---

_For questions or contributions, contact the Advisory AI Guild (Slack #guild-advisory-ai) and tag Docs Guild reviewers._