Advisory AI Architecture (service-level detail)

Owner: Docs Guild & Advisory AI Guild • Status: Draft

This document decomposes how Advisory AI — the AI-assisted advisory and remediation plane of the Stella Ops release control plane — turns immutable evidence into deterministic, explainable outputs. It complements the canonical Advisory AI architecture with service-level views, data flows, and integration checklists.

Reconciliation note. Some design elements below (a named ProfileRegistry, a SQL-backed AdvisoryOutputStore table, an enumerated profile catalog with TTL defaults) describe the original target design. The shipped implementation differs: profiles are free-form labels, outputs are file-backed, and there is no profile registry. Where this document and architecture.mddisagree, architecture.md (reconciled against src/) is authoritative.

1. High-level flow

Concelier / Excititor / SBOM / Policy
            | (retrievers)
            v
   +----------------------------+
   | AdvisoryPipelineOrchestrator |
   |    (plan generation)        |
   +----------------------------+
            | plan + cache key
            v
   +----------------------------+
   | Guarded Prompt Runtime      |
   |   (profile-specific)        |
   +----------------------------+
            | validated output + citations
            v
   +----------------------------+
   | Cache & Provenance          |
   |   (PostgreSQL + DSSE opt.)  |
   +----------------------------+
            |                 \
            v                  v
       REST API           CLI / Console

Key stages:

1. Retrieval – deterministic chunkers pull AOC-compliant data: Concelier advisories, Excititor VEX statements, SBOM context, Policy explain traces, optional runtime telemetry.
2. Plan generation – the orchestrator builds an AdvisoryTaskPlan (Summary / Conflict / Remediation) containing budgets, prompt template IDs, cache keys, and metadata.
3. Guarded inference – profile-specific prompt runners execute with guardrails (redaction, injection defence, citation enforcement). Failures are logged and downstream consumers receive deterministic errors.
4. Persistence – outputs are hashed (outputHash), referenced with inputDigest, optionally sealed with DSSE, and exposed for CLI/Console consumption.

2. Component responsibilities

3. Data contracts

3.1 AdvisoryTaskRequest

{
  "taskType": "Summary",
  "advisoryKey": "csaf:redhat:RHSA-2025:1001",
  "artifactId": "registry.stella-ops.internal/runtime/api",
  "artifactPurl": "pkg:oci/runtime-api@sha256:d2c3...",
  "policyVersion": "2025.10.1",
  "profile": "fips-local",
  "preferredSections": ["Summary", "Remediation"],
  "forceRefresh": false
}

• taskType ∈ Summary|Conflict|Remediation.
• Provide either artifactId or artifactPurl for remediation tasks (unlocks dependency analysis).
• forceRefresh bypasses cache and regenerates output (deterministic with identical inputs).

3.2 AdvisoryPipelinePlanResponse

Returned when plan preview is enabled; summarises chunk and vector usage so operators can verify evidence.

{
  "taskType": "Summary",
  "cacheKey": "adv-summary:csaf:redhat:RHSA-2025:1001:fips-local",
  "budget": { "promptTokens": 1024, "completionTokens": 256 },
  "chunks": [{"documentId": "doc-1", "chunkId": "doc-1:0001", "section": "Summary"}],
  "vectors": [{"query": "Summary query", "matches": [{"chunkId": "doc-1:0001", "score": 0.92}]}],
  "sbom": {
    "artifactId": "registry.stella-ops.internal/runtime/api",
    "versionTimelineCount": 8,
    "dependencyPathCount": 5,
    "dependencyNodeCount": 17
  }
}

3.3 Output envelope

See the Advisory AI API guide §6. Each response includes inputDigest, outputHash, Markdown content, citations, TTL, and context summary to support offline replay.

4. Profiles & runtime selection

Profile selection is controlled via Authority configuration (advisoryAi.allowedProfiles). Remote profiles require tenant consent, allowlisted endpoints, and custom SLIs to track latency/error budgets.

5. Guardrails & validation pipeline

1. Prompt preparation – sanitized context injected into templated prompts (Liquid/Handlebars). Sensitive tokens scrubbed before render.
2. Prompt allowlist – each template fingerprinted; runtime rejects prompts whose hash is not documented.
3. Response schema – JSON validator ensures sections, severity tags, and citation arrays meet contract.
4. Citation resolution – referenced [n] items must map to context chunk identifiers.
5. DSSE sealing (optional) – outputs can be sealed with the Advisory AI signing key; DSSE bundle stored alongside cache artefact.
6. Audit trail – guardrail results logged (advisory_ai.guardrail.blocked|passed) with tenant and trace IDs.

6. Caching & storage model

Cache misses trigger orchestration and inference; hits return stored artefacts immediately. TTL expiry removes entries unless forceRefresh has already regenerated them.

Additional live runtime tables:

Runtime connection precedence for these tables is AdvisoryAI:Storage:ConnectionString -> ConnectionStrings:Default -> Database:ConnectionString. The web host auto-migrates this schema on startup and refuses live startup when no durable store is configured. Process-local Null*, NoOp*, and InMemory* runtime bindings are only legal when the environment is Development or Testing and AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true.

7. Telemetry & SLOs

Names corrected 2026-07-12 to the emitted instruments (architecture.md §9 is the reconciled list; this file’s aspirational names — advisory_ai_requests_total{…profile}, advisory_ai_cache_hits_total, advisory_ai_remote_profile_requests_total — were not emitted, and there is no profile label). The real instruments (meter StellaOps.AdvisoryAI, AdvisoryPipelineMetrics.cs):

• advisory_plans_created, advisory_plans_queued, advisory_plans_processed (counters)
• advisory_outputs_stored (counter)
• advisory_ai_guardrail_blocks_total, advisory_ai_validation_failures_total (counters)
• advisory_plan_build_duration_seconds, advisory_ai_latency_seconds, advisory_ai_citation_coverage_ratio (histograms)

Logs include traceId, tenant, task, profile, outputHash, cacheStatus (hit|miss|bypass). Prompt bodies are never logged; guardrail violations log sanitized excerpts only.

Suggested SLOs:

• Latency: P95 ≤ 3s (local), ≤ 8s (remote).
• Availability: 99.5% successful responses per tenant over 7 days.
• Guardrail block rate: ≤ 1%; investigate higher values.

8. Deployment & offline guidance

• Package prompts, guardrail configs, profile manifests, and local model weights in the Offline Kit.
• Remote profiles remain disabled until Authority admins set advisoryAi.remoteProfiles and record tenant consent.
• Export Center reads cached outputs using advisory-ai:view and benefits from DSSE sealing when enabled.

9. Checklist

• [ ] AdvisoryRetrievalService wired to the SBOM context client (AIAI-31-002).
• [ ] Authority scopes (advisory-ai:*, aoc:verify) validated in staging.
• [ ] Guardrail library reviewed by Security Guild (AIAI-31-005).
• [ ] Cache TTLs/DSSE policy signed off by Platform & Compliance.
• [ ] Observability dashboards published (DOCS-OBS backlog).
• [ ] Offline Kit bundle updated with prompts, guardrails, local profile assets.

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