Expose profile inspection through the engine

engine.go

@@ -78,14 +78,14 @@ var (
 	ErrValidation = errors.New("failed to validate output")
 )
 
-// Engine prepares and runs Promptkit prompt requests.
+// Engine inspects profiles and prepares and runs Promptkit prompt requests.
 //
-// An Engine is safe for concurrent calls to [Engine.Prepare],
-// [Engine.PrepareExecution], [Engine.Run], and [Engine.RunPrepared]. Each
-// Engine owns independent backend-capacity pools that coordinate Run and
-// RunPrepared admission and model generation. Injected collaborators may still
-// be invoked concurrently across different backend pools or for unlimited
-// backends.
+// An Engine is safe for concurrent calls to [Engine.InspectProfile],
+// [Engine.Prepare], [Engine.PrepareExecution], [Engine.Run], and
+// [Engine.RunPrepared]. Each Engine owns independent backend-capacity pools
+// that coordinate Run and RunPrepared admission and model generation. Injected
+// collaborators may still be invoked concurrently across different backend
+// pools or for unlimited backends.
 type Engine struct {
 	runner *usecase.Runner
 }
@@ -428,6 +428,46 @@ func fileSource(name string) (fs.FS, string, error) {
 	return os.DirFS(dir), filepath.ToSlash(base), nil
 }
 
+// InspectProfile resolves one explicit profile without selecting a prompt or
+// starting execution work.
+//
+// InspectProfile trims surrounding whitespace from profileID and looks up the
+// resulting nonblank ID exactly and case-sensitively through the engine's
+// ordinary in-memory, configured-source, and built-in profile precedence. It
+// applies framework defaults, the selected backend, and then the selected
+// profile to EffectiveModelParams without a request override. BackendID is
+// empty for an endpoint-only profile.
+//
+// APIKeyEnv in the returned target is an environment-variable name, never its
+// value. APIKeyRequired instead reports a direct credential requirement and is
+// mutually exclusive with a nonblank APIKeyEnv. InspectProfile neither derives
+// an ID from a prompt default_profile nor checks credential availability, so an
+// absent or blank named environment variable is not an error.
+//
+// The returned ProfileInspection and all nested mutable values are
+// caller-owned. Filesystem-backed inspection is a point-in-time lookup and
+// does not freeze the profile for a later execution. This method does not load
+// a prompt, render, read artifacts or schemas, admit backend capacity, contact
+// a provider, or generate model output.
+//
+// A nil Engine returns an error matching ErrInvalidConfig. A blank profile ID
+// matches ErrInvalidRequest. An absent exact ID matches ErrProfileNotFound and
+// not ErrProfileLoad. Malformed or unreadable profile data, an unknown backend,
+// or an invalid resolved target matches ErrProfileLoad. Cancellation during
+// profile loading matches ErrProfileLoad while preserving the context error.
+// InspectProfile returns no partial result on error.
+func (e *Engine) InspectProfile(ctx context.Context, profileID string) (*ProfileInspection, error) {
+	if e == nil || e.runner == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+
+	inspection, err := e.runner.InspectProfile(ctx, profileID)
+	if err != nil {
+		return nil, mapPublicError(err)
+	}
+	return fromDomainProfileInspection(inspection), nil
+}
+
 // Prepare resolves and renders a prompt request without calling an LLM.
 //
 // Prepare selects the prompt and profile, resolves any selected backend and