Advisory AI Overview

Updated: 2025-11-03 • Owner: Docs Guild & Advisory AI Guild • Status: Draft

Audience: operators, platform engineers, and security/compliance reviewers who consume or operate Stella Ops Advisory AI.

Advisory AI is the retrieval-augmented assistant in the Stella Ops release control plane. It synthesises Concelier (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.

This page is the orientation read. For deep technical diagrams and sequence flows, see architecture.md; for the public API surface, see guides/api.md.

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, and policy digests.	Concelier, 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, and emit telemetry.	PostgreSQL cache store, Export Center, Observability stack

See architecture.mdfor deep technical diagrams and sequence flows.

3. Guardrails & compliance

Aggregation-only – only raw facts from authorised sources are consumed; no on-the-fly enrichment beyond deterministic tooling.
Citation-first – every sentence referencing external evidence must cite a canonical paragraph/statement identifier.
Content filters – redaction, policy-based profanity filters, and prompt allowlists are applied before model invocation.
Deterministic cache – outputs are stored with inputDigest and outputHash; force-refresh regenerates the same output unless upstream evidence changes.
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 guides/api.md.

5. Data sources & provenance

Advisories – Concelier 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 the Offline Kit; FIPS-approved crypto.
`gost-local`	Sovereign clusters	GOST-compliant crypto and 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.