Expose profile inspection through the engine

types.go

@@ -320,6 +320,25 @@ type ExecutionTarget struct {
 	ExtraParams map[string]any `json:"extra_params"`
 }
 
+// ProfileInspection is the caller-owned result of [Engine.InspectProfile].
+// It has no stable JSON representation.
+//
+// EffectiveModelParams contains a copied effective target. APIKeyRequired is
+// separate from that target to preserve ExecutionTarget's general execution
+// and stable JSON contracts.
+type ProfileInspection struct {
+	// ProfileID is the trimmed, exact profile ID inspected by the engine.
+	ProfileID string
+	// EffectiveModelParams contains framework defaults overlaid by the selected
+	// backend and then the profile, without a request override. APIKeyEnv is an
+	// environment-variable name, never its credential value.
+	EffectiveModelParams ExecutionTarget
+	// APIKeyRequired reports that a later execution must supply a direct API
+	// key or an explicit request environment override. It is mutually exclusive
+	// with a nonblank EffectiveModelParams.APIKeyEnv.
+	APIKeyRequired bool
+}
+
 // ExecutionTargetOverride represents per-request runtime setting overrides and
 // has no stable JSON representation.
 //