Operator–LLM API contract

The operator and the LLM service communicate over HTTP/JSON. This document describes the request/response schema and versioning expectations. The LLM service also exposes OpenAPI at GET /openapi.json.

Endpoints

Method Path Purpose
POST /analyze Submit a failed workload; returns analysis and optional patch.
GET /health Liveness probe.
GET /ready Readiness probe.
GET /analyses List recent analyses (summary, root_cause, recommendation, action).
GET /reports List step-by-step reports (LLM steps + operator outcome).
POST /report-outcome Operator callback when a patch is applied (body: resource_kind, resource_name, namespace, outcome).

POST /analyze

Request (operator → LLM)

{
  "resource_kind": "Pod" | "Deployment" | "Job",
  "resource_name": "string",
  "namespace": "string",
  "reason": "string",
  "events": [ { "type", "reason", "message", "firstTimestamp", "lastTimestamp" } ],
  "spec": { ... },
  "recent_logs": [ "string" ],
  "historical_logs": [ "string" ]
}
  • events, recent_logs, historical_logs may be empty arrays; the LLM service accepts null and coerces to [].
  • spec is the workload spec (e.g. Deployment.spec or Pod.spec) after redaction.

Response (LLM → operator)

{
  "summary": "string",
  "root_cause": "string",
  "recommendation": "string",
  "action": {
    "type": "k8s_patch",
    "target": { "kind", "namespace", "name" },
    "patch_type": "application/strategic-merge-patch+json",
    "patch": { ... }
  } | null
}
  • If action is present and type is k8s_patch, the operator may apply patch to the resource identified by target (when APPLY_MODE=auto and scope allows). The patch is filtered server-side to allowed fields (image, env, replicas, resources).

Versioning and compatibility

  • Adding optional fields to the request or response is considered backward compatible. The operator or LLM may ignore unknown fields.
  • Changing or removing required fields or changing semantics of existing fields will be done with a version bump (e.g. a new path like /v2/analyze or a version header). See ROADMAP – Versioning and releases.
  • The OpenAPI schema generated by the LLM service (FastAPI) is the current source of truth for the analyze endpoint; this doc provides a stable summary for humans and for the operator implementation.

POST /report-outcome

Body (JSON):

{
  "resource_kind": "string",
  "resource_name": "string",
  "namespace": "string",
  "outcome": "applied"
}

The LLM service uses this to append an “Operator applied patch” step to the latest matching report (for GET /reports).