StellaOps Advisory AI

Advisory AI is the retrieval-augmented assistant that synthesizes advisory and VEX evidence into operator-ready summaries, conflict explanations, and remediation plans with strict provenance.

Responsibilities

• Generate policy-aware advisory summaries with citations back to Concelier and Excititor evidence.
• Explain conflicting advisories/VEX statements using weights from VEX Lens and Policy Engine.
• Propose remediation hints aligned with Offline Kit staging and export bundles.
• Expose API/UI surfaces with guardrails on model prompts, outputs, and retention.

Contributor quickstart

• Read docs/modules/advisory-ai/AGENTS.md before making changes; it lists required docs, determinism/offline rules, and working directory scope.
• Keep outputs aggregation-only with stable ordering and UTC timestamps; tests must cover guardrails, tenant safety, and provenance.
• When updating contracts/telemetry, sync the relevant docs here and cross-link from sprint Decisions & Risks.

Key components

• RAG pipeline drawing from Concelier, Excititor, VEX Lens, Policy Engine, and SBOM Service data.
• Prompt templates and guard models enforcing provenance and redaction policies.
• Pluggable inference: a local in-house chat inference path plus optional self-hosted LLM-provider adapters (Inference/LlmProviders/ — Claude, Gemini, llama-server, and similar) gated by Adapters:Llm:Enabled. The pipeline inference client (AdvisoryInferenceClient) supports Local and Remote modes (AdvisoryAiInferenceMode) with deterministic caching of generated artefacts. (Remote mode targets a self-hosted external inference tier; this is an on-prem/air-gap-first platform — no managed-cloud inference provider is wired by default.)
• AdvisoryAI Knowledge Search (AKS) for deterministic docs/API/Doctor retrieval: docs/modules/advisory-ai/knowledge-search.md.

API surface

All business endpoints are served by the advisory-ai-web service under the /v1/advisory-ai/* prefix and authenticated via the gateway-signed identity envelope (verified by UseIdentityEnvelopeAuthentication(); raw X-User-Id/X-Tenant-Id/X-StellaOps-Scopes headers are stripped at inbound by InboundIdentityHeaderStripMiddleware). Endpoints attach named authorization policies from AdvisoryAIPolicies (StellaOps.AdvisoryAI.WebService/Security/AdvisoryAIPolicies.cs). All requests are also rate-limited under the advisory-ai policy (token bucket, 30 req/min per X-StellaOps-Client).

Scopes (canonical names in StellaOps.Auth.Abstractions/StellaOpsScopes.cs):

• advisory-ai:view — read-only artefacts (outputs, runs, attestations, evidence packs); satisfies ViewPolicy.
• advisory-ai:operate — inference/workflow execution (pipeline, explain, remediate, chat, search); implies view; satisfies OperatePolicy.
• advisory-ai:admin — administrative control; implies operate; satisfies AdminPolicy.

Endpoint families (verbs/paths grounded in WebService/Program.cs and the Endpoints/*.cs route groups):

• Pipeline — POST /v1/advisory-ai/pipeline/{taskType}, POST /v1/advisory-ai/pipeline:batch (operate); GET /v1/advisory-ai/outputs/{cacheKey}?taskType=&profile= (view). taskType ∈ summary | conflict | remediation (AdvisoryTaskType enum).
• Explain / companion — POST /v1/advisory-ai/explain (operate), GET /v1/advisory-ai/explain/{explanationId}/replay (view), POST /v1/advisory-ai/companion/explain (operate).
• Remediation — POST /v1/advisory-ai/remediation/plan, POST /v1/advisory-ai/remediation/apply, GET /v1/advisory-ai/remediation/status/{prId}; plus alias POST /v1/advisory-ai/remediate.
• Policy Studio — POST /v1/advisory-ai/policy/studio/parse, .../generate are wired; .../validate and .../compile currently return 501 Not Implemented (not yet wired to durable generated-rule storage).
• Runs (RunEndpoints) — /v1/advisory-ai/runs group: create/query/get, timeline, events, user/assistant turns, propose/execute actions, approval request/decide, artifacts, complete/cancel/handoff/attest, and GET .../active and GET .../pending-approval. Returns RunDto/RunEventDto/RunQueryResultDto; RunStatus ∈ Created=0 | Active=1 | PendingApproval=2 | Approved=3 | Rejected=4 | Completed=5 | Cancelled=6 | Failed=7 | Expired=8 (terminal states immutable).
• Consent / justification — GET|POST|DELETE /v1/advisory-ai/consent, POST /v1/advisory-ai/justify, GET /v1/advisory-ai/rate-limits.
• Chat — controlled conversational interface via MapChatEndpoints(). The legacy /v1/advisory-ai/conversations* surface is deprecated in favor of /api/v1/chat/* (sunset 2026-12-31 UTC).
• Attestations / Evidence packs — MapAttestationEndpoints(), MapEvidencePackEndpoints().
• Search — Knowledge Search, Unified Search, Search Analytics/History, and Search Feedback/Quality endpoints (MapKnowledgeSearchEndpoints(), MapUnifiedSearchEndpoints(), MapSearchAnalyticsEndpoints(), MapSearchFeedbackEndpoints()).
• LLM adapter — exposed only when AdvisoryAI:Adapters:Llm:Enabled=true (MapLlmAdapterEndpoints()).
• Health — /health, /health/live, /health/ready, /health/model (anonymous). /health/ready reports ready with modelGateway.status=disabled when chat is disabled.

Integrations & dependencies

• Authority for tenant-aware access control. The advisory-ai-web service acquires its own client_credentials token (seeded OAuth client stellaops-advisory-ai-internal via the Authority seed baseline S001_v1_authority_operational_baseline.sql, which folded in the pre-1.0 S005_advisory_ai_authority_client.sql) to authenticate outbound calls to the vex-internal, scanner-internal, policy-internal, graph-internal, and timeline-internal HTTP clients.
• Policy Engine for context-specific decisions and explain traces.
• Console/CLI for interaction surfaces.
• Export Center/Vuln Explorer for embedding generated briefs.

Operational notes

• Model cache management and offline bundle packaging per Epic 8 requirements.
• Metrics are published on the StellaOps.AdvisoryAI meter (AdvisoryPipelineMetrics, AdvisoryAiMetrics). Pipeline/latency monitoring uses advisory_ai_latency_seconds, guardrail/validation counters advisory_ai_guardrail_blocks_total and advisory_ai_validation_failures_total, and the citation-coverage histogram advisory_ai_citation_coverage_ratio. Request/queue counters include advisory_ai_pipeline_requests_total, advisory_ai_pipeline_messages_enqueued_total, and advisory_ai_pipeline_messages_processed_total; plan counters include advisory_plans_created, advisory_plans_queued, advisory_plans_processed, and advisory_outputs_stored.
• Alert policies fire when advisory_ai_guardrail_blocks_total or advisory_ai_validation_failures_total breach burn-rate thresholds (5 blocks/min or validation failures > 1% of traffic) and when latency p95 exceeds 30s. (Dashboard/alert thresholds are operator-defined; verify against your telemetry deployment.)
• Tracing uses the AdvisoryAiActivitySource (spans such as advisory_ai.plan_request, advisory_ai.explain, advisory_ai.remediation_plan, advisory_ai.policy_parse, advisory_ai.justify).
• Redaction policies validated against security/LLM guardrail tests.
• Guardrail behaviour, blocked phrases, and operational alerts are detailed in docs/security/assistant-guardrails.md.

Outputs & artefacts

• Durable state (PostgreSQL): runtime state lives in the advisoryai schema, auto-migrated on startup from embedded SQL (StellaOps.AdvisoryAI/Storage/Migrations/*.sql). Tables include chat audit (chat_sessions, chat_messages, chat_policy_decisions, chat_tool_invocations, chat_evidence_links), knowledge/unified search (kb_doc, kb_chunk, api_spec, api_operation, doctor_search_projection, entity_alias, search_events, search_history, search_feedback, search_quality_alerts), and AI runtime state (ai_consents, ai_run_attestations, ai_claim_attestations, runtime_explanations, runtime_policy_intents, runtime_runs, runtime_chat_settings_overrides, conversations, turns). Connection string is supplied via ADVISORYAI__AdvisoryAI__Storage__ConnectionString.
• File-backed queue/plan/output stores: the plan cache and output store persist deterministic artefacts to filesystem directories (ADVISORYAI__AdvisoryAI__Queue__DirectoryPath, ...__Storage__PlanCacheDirectory, ...__Storage__OutputDirectory). In the compose stack these default to /var/lib/advisory-ai/{queue,plans,outputs} (web) and /tmp/advisory-ai/{queue,plans,outputs} (worker); the web and worker containers share the named volumes advisory-ai-queue, advisory-ai-plans, advisory-ai-outputs.
• Service surfaces: outputs are read back via GET /v1/advisory-ai/outputs/{cacheKey} and immutable run state via the /v1/advisory-ai/runs/* endpoints (run query/get/timeline). Completed runs can be attested via POST /v1/advisory-ai/runs/{runId}/attest.
• Observability: metrics are emitted on the StellaOps.AdvisoryAI meter (see Operational notes for the canonical metric names). Dashboards and alerts must reference these canonical names to avoid drift.

NOT IMPLEMENTED (verify before relying): earlier drafts of this doc described an /ops/advisory-ai/runs NDJSON status stream, an advisory_ai_run_completed worker event, and an advisory-ai-bundle.tgz offline export. None of these were found in src/AdvisoryAI/. The canonical runs surface is /v1/advisory-ai/runs (not /ops/...); no advisory_ai_run_completed event emission or advisory-ai-bundle.tgz packaging exists in the worker. Treat these as roadmap/forward design until implemented.

Deployment & configuration

• Containers: advisory-ai-web (image stellaops/advisory-ai-web) fronts the API/cache while advisory-ai-worker (image stellaops/advisory-ai-worker) drains the queue and executes prompts. Container names in the compose stack are stellaops-advisory-ai-web and stellaops-advisory-ai-worker. They share the named volumes advisory-ai-queue, advisory-ai-plans, and advisory-ai-outputs for the file-backed queue/plan/output stores.
• Configuration prefix: environment variables are bound with the ADVISORYAI__ prefix, and the options live under the AdvisoryAI section — so the full double-underscore form is ADVISORYAI__AdvisoryAI__<...>. Examples from the compose stack: ADVISORYAI__AdvisoryAI__SbomBaseAddress, ADVISORYAI__AdvisoryAI__Queue__DirectoryPath, ADVISORYAI__AdvisoryAI__Storage__ConnectionString, ADVISORYAI__AdvisoryAI__Storage__PlanCacheDirectory, ADVISORYAI__AdvisoryAI__Storage__OutputDirectory. Knowledge/unified search adapters are configured under ADVISORYAI__KnowledgeSearch__*.
• Runtime bindings: production-like hosts require durable PostgreSQL/runtime integrations and fail closed when they are absent. Local Null*, NoOp*, and InMemory* harnesses require both a Development/Testing environment and AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true (AdvisoryAiRuntimeBindingOptions).
• Remote inference toggle: Set ADVISORYAI__AdvisoryAI__Inference__Mode=Remote to send sanitized prompts to an external inference tier (AdvisoryAiInferenceMode ∈ Local | Remote). Provide ADVISORYAI__AdvisoryAI__Inference__Remote__BaseAddress (and optional ...__ApiKey, ...__Timeout; default timeout 30s) to complete the circuit. On a remote failure or timeout the AdvisoryInferenceClient throws (InvalidOperationException/TimeoutException) rather than silently degrading — the caller is responsible for handling the error.
• Chat / LLM providers: chat is gated by ADVISORYAI__AdvisoryAI__Chat__Enabled and configured under ADVISORYAI__AdvisoryAI__Chat__Inference__* (provider, base URL, model, model digest, max tokens, seed, capability validation). External LLM-provider adapters are enabled by ADVISORYAI__AdvisoryAI__Adapters__Llm__Enabled with provider configs under ADVISORYAI__AdvisoryAI__LlmProviders__ConfigDirectory.
• Compose: the canonical deployment lives in devops/compose/docker-compose.stella-services.yml. See docs/modules/advisory-ai/deployment.md for commands.

Stale reference (verify): a prior draft pointed at packaged manifests under ops/advisory-ai/; no such directory exists in the repo. The compose definition is under devops/compose/.

CLI usage

• stella advise run <summary|conflict|remediation> --advisory-key <id> [--artifact-id id] [--artifact-purl purl] [--policy-version v] [--profile profile] [--section name] [--force-refresh] [--timeout seconds]
  • Requests an advisory plan from the web service, enqueues execution, then polls for the generated output (default wait 120 s, single check if --timeout 0).
  • <task> is one of summary | conflict | remediation (AdvisoryAiTaskType); also supports [--format table|json|markdown] and [--output path]. The request hits POST v1/advisory-ai/pipeline/{taskType} and polls GET v1/advisory-ai/outputs/{cacheKey}.
  • Renders plan metadata (cache key, prompt template, token budget), guardrail state, provenance hashes, signatures, and citations.
• Convenience aliases that call the same handler with a fixed task type: stella advise summarize (summary), stella advise explain (conflict), stella advise remediate (remediation). stella advise batch <advisory-keys...> runs the summary task over multiple advisories in one invocation. stella advise open-pr drives remediation apply (POST v1/advisory-ai/remediation/apply).
• Chat sub-commands (AdviseChatCommandGroup): stella advise ask <query> (evidence-backed Q&A; --file for batch JSONL, --image, --digest, --environment, --conversation-id, --evidence), stella advise chat-doctor, stella advise chat-settings get|update|clear, and stella advise export. Chat requires a configured LLM provider (stella setup --step llm).
  • The CLI resolves the service URL from the AdvisoryAiUrl option, bound from STELLAOPS_ADVISORYAI_URL / StellaOps:AdvisoryAiUrl / AdvisoryAiUrl; otherwise it reuses the backend URL. Requests carry scopes via the X-StellaOps-Scopes header.

Implementation Status

Current Phase: Production-ready (Epic 8 - Advisory AI Assistant)

Completed Milestones:

• RAG pipeline with Concelier/Excititor/VEX Lens integration
• Guardrail enforcement and provenance tracking
• AI investigation runs with approval workflow and run attestation; AI attestations and evidence packs
• Knowledge Search / Unified Search with analytics, history, and feedback surfaces
• CLI (stella advise …) and the /v1/advisory-ai/* API with deterministic outputs

Known gaps / not yet wired:

• Policy Studio validate and compile stages return 501 Not Implemented (not yet wired to durable generated-rule storage); parse and generate are available.
• The legacy /v1/advisory-ai/conversations* chat surface is deprecated in favor of /api/v1/chat/* (sunset 2026-12-31 UTC).

Active Workstreams:

• Ongoing: Documentation, telemetry, and runbook alignment with sprint outcomes
• Epic 8 stories tracked in implementation_plan.md

Epic alignment

• Epic 8: Advisory AI Assistant
• DOCS-AI stories tracked in implementation_plan.md