Design: LLM-assisted operations

Status: Draft · Last updated: 2026-04-20

An LLM-assisted layer for grounded answers, draft change bundles, and import/reconciliation help—without making the model a second source of truth. Reads inventory through APIs, proposes structured actions, and executes writes only through the same paths as human operators (audit, RBAC, approval where required).

Goals

Goal	User-visible outcome
Throughput	Faster path from natural language to validated API payloads, bulk mappings, and runbooks.
Trust	Answers cite inventory objects; “unknown” is explicit when data is missing.
Safety	No silent writes; privileged actions use the same gates as today.
Operability	Observable, rate-limited, tenant-scoped usage.

Non-goals (initial phases)

Replacing deterministic policy engines or compliance checks with model judgment.
Unrestricted autonomous remediation without human or policy approval.
Training a bespoke foundation model (hosted or self-hosted inference assumed).
Storing full customer topologies in an external vector DB without explicit residency/retention decisions.

Personas and scenarios

Persona	Scenario	Assistant role
NetOps / NOC	Dependencies / incident context	Search + resource graph; summarize with citations.
DCIM / field	Maintenance planning	Draft change bundle; highlight conflicts.
Automation engineer	Recurring procedures	Draft steps, variables, guardrails for jobs/plugins.
Data steward	Vendor export reconciliation	Column → schema mapping preview for bulk import.
New operator	Learn the model in context	Explain this record and links from retrieved fields.

Functional requirements (summary)

Grounded Q&A (read path)

Optional page context (resourceType, id). Tools: GET /v1/search, GET /v1/resource-view/{resourceType}/{id}, GET /v1/resource-graph/{resourceType}/{id}. Short answers with citations; no invented IDs when retrieval is empty.

Change assistance (write path)

Machine-readable proposals; UI preview; execution via existing mutating REST with RBAC.

Bulk import assistance

Column mapping, coercion notes, validation warnings before bulk import endpoints.

Incident / ticket assist (optional)

Extract identifiers from pasted text; resolve via search; return linked inventory summary.

System architecture

Copilot orchestrator behind the BFF; tool-calling loop; core domain and workers remain authoritative for state changes.

Tooling contract (v1 minimum)

Tool	Purpose	API
`search`	Find objects	`GET /v1/search?q=&limit=`
`get_resource_view`	Fields + graph	`GET /v1/resource-view/…`
`get_resource_graph`	Graph JSON	`GET /v1/resource-graph/…`

Tools run with the caller’s credentials; idempotency keys where supported; hard limits per message/session.

Security, privacy, compliance

Data minimization and optional redaction before model calls.
Residency documentation; region pinning / private endpoints for regulated customers.
Retention policy for prompts/responses (none, encrypted TTL, opt-in review).
Prompt-injection mitigations for text stored in inventory fields.
Audit: user, tenant, tools, object ids, whether a mutation ran.

Observability

Latency, tokens, tool errors, rate limits, tracing spans per request and tool call, user-safe error surfaces.

UX surfaces

Global assistant with page context; contextual actions on list/detail; confirm dialog for proposals; strong empty/error states.

Phased delivery

Phase	Scope	Exit criteria
P0	Grounded Q&A, citations, no writes	Pilot spot-checks on hallucination rate
P1	Proposals + preview + REST execution	Dry-run path for defined resource types
P2	Bulk import mapping	Faster time-to-first-good import
P3	Ticket paste + optional risk narration	Triage workflow adopted by a team

Success metrics & risks

Time to answer vs. manual navigation; proposal acceptance rate; import mapping edits; zero unauthorized mutations by design. Mitigations: citations, injection handling, budgets, private LLM options.

Open questions

Embeddings scope (docs-only vs. object embeddings).
Multi-tenant deployment topology for copilot.
ITSM integration for certain mutations.
Internationalization.

Full specification: docs/design-llm-assistant.md

← Back to documentation