git.stella-ops.org/docs/modules/advisory-ai/architecture.md

Advisory AI architecture

Captures the retrieval, guardrail, and inference packaging requirements defined in the Advisory AI implementation plan and related module guides.

1) Goals

• Summarise advisories/VEX evidence into operator-ready briefs with citations.
• Explain conflicting statements with provenance and trust weights (using VEX Lens & Excititor data).
• Suggest remediation plans aligned with Offline Kit deployment models and scheduler follow-ups.
• Operate deterministically where possible; cache generated artefacts with digests for audit.

2) Pipeline overview

                       +---------------------+
   Concelier/VEX Lens  |  Evidence Retriever |
   Policy Engine ----> |  (vector + keyword) | ---> Context Pack (JSON)
   Zastava runtime     +---------------------+
                               |
                               v
                        +-------------+
                        | Prompt      |
                        | Assembler   |
                        +-------------+
                               |
                               v
                        +-------------+
                        | Guarded LLM |
                        | (local/host)|
                        +-------------+
                               |
                               v
                        +-----------------+
                        | Citation &     |
                        | Validation      |
                        +-----------------+
                               |
                               v
                        +----------------+
                        | Output cache   |
                        | (hash, bundle) |
                        +----------------+

3) Retrieval & context

• Hybrid search: vector embeddings (SBERT-compatible) + keyword filters for advisory IDs, PURLs, CVEs.
• Context packs include:
  • Advisory raw excerpts with highlighted sections and source URLs.
  • VEX statements (normalized tuples + trust metadata).
  • Policy explain traces for the affected finding.
  • Runtime/impact hints from Zastava (exposure, entrypoints).
  • Export-ready remediation data (fixed versions, patches).
• SBOM context retriever (AIAI-31-002) hydrates:
  • Version timelines (first/last observed, status, fix availability).
  • Dependency paths (runtime vs build/test, deduped by coordinate chain).
  • Tenant environment flags (prod/stage toggles) with optional blast radius summary.
  • Service-side clamps: max 500 timeline entries, 200 dependency paths, with client-provided toggles for env/blast data.

Retriever requests and results are trimmed/normalized before hashing; metadata (counts, provenance keys) is returned for downstream guardrails. Unit coverage ensures deterministic ordering and flag handling.

All context references include content_hash and source_id enabling verifiable citations.

4) Guardrails

• Prompt templates enforce structure: summary, conflicts, remediation, references.
• Response validator ensures:
  • No hallucinated advisories (every fact must map to input context).
  • Citations follow [n] indexing referencing actual sources.
  • Remediation suggestions only cite policy-approved sources (fixed versions, vendor hotfixes).
• Moderation/PII filters prevent leaking secrets; responses failing validation are rejected and logged.

5) Deterministic tooling

• Version comparators — offline semantic version + RPM EVR parsers with range evaluators. Supports chained constraints (>=, <=, !=) used by remediation advice and blast radius calcs.
  • Registered via AddAdvisoryDeterministicToolset for reuse across orchestrator, CLI, and services.
• Orchestration pipeline — see orchestration-pipeline.md for prerequisites, task breakdown, and cross-guild responsibilities before wiring the execution flows.
• Planned extensions — NEVRA/EVR comparators, ecosystem-specific normalisers, dependency chain scorers (AIAI-31-003 scope).
• Exposed via internal interfaces to allow orchestrator/toolchain reuse; all helpers stay side-effect free and deterministic for golden testing.

6) Output persistence

• Cached artefacts stored in advisory_ai_outputs with fields:
  • output_hash (sha256 of JSON response).
  • input_digest (hash of context pack).
  • summary, conflicts, remediation, citations.
  • generated_at, model_id, profile (Sovereign/FIPS etc.).
  • signatures (optional DSSE if run in deterministic mode).
• Offline bundle format contains summary.md, citations.json, context_manifest.json, signatures/.

7) Profiles & sovereignty

• Profiles: default, fips-local (FIPS-compliant local model), gost-local, cloud-openai (optional, disabled by default). Each profile defines allowed models, key management, and telemetry endpoints.
• CryptoProfile/RootPack integration: generated artefacts can be signed using configured CryptoProfile to satisfy procurement/trust requirements.

8) APIs

• POST /v1/advisory-ai/summaries — generate (or retrieve cached) summary for {advisoryKey, artifactId, policyVersion}.
• POST /v1/advisory-ai/conflicts — explain conflicting VEX statements with trust ranking.
• POST /v1/advisory-ai/remediation — fetch remediation plan with target fix versions, prerequisites, verification steps.
• GET /v1/advisory-ai/outputs/{hash} — retrieve cached artefact (used by CLI/Console/Export Center).

All endpoints accept profile parameter (default fips-local) and return output_hash, input_digest, and citations for verification.

9) Observability

• Metrics: advisory_ai_requests_total{profile,type}, advisory_ai_latency_seconds, advisory_ai_validation_failures_total.
• Logs: include output_hash, input_digest, profile, model_id, tenant, artifacts. Sensitive context is not logged.
• Traces: spans for retrieval, prompt assembly, model inference, validation, cache write.

10) Operational controls

• Feature flags per tenant (ai.summary.enabled, ai.remediation.enabled).
• Rate limits (per tenant, per profile) enforced by Orchestrator to prevent runaway usage.
• Offline/air-gapped deployments run local models packaged with Offline Kit; model weights validated via manifest digests.