git.stella-ops.org/docs/advisory-ai/overview.md

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.