feat: add guardrails to model card report (#445)

Signed-off-by: Ruben Romero Montes <[email protected]>

Author: ruromero

pom.xml

@@ -48,7 +48,7 @@
     <deploy-plugin.version>3.1.1</deploy-plugin.version>
 
     <!-- Dependencies -->
-    <exhort-api.version>1.0.16</exhort-api.version>
+    <exhort-api.version>1.0.17</exhort-api.version>
     <sentry.version>7.8.0</sentry.version>
     <spdx.version>2.0.2</spdx.version>
     <htmlunit.version>4.11.1</htmlunit.version>

src/main/java/com/redhat/exhort/model/modelcards/Guardrail.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2025 Red Hat, Inc. and/or its affiliates
+ * and other contributors as indicated by the @author tags.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.redhat.exhort.model.modelcards;
+
+import java.util.List;
+import java.util.Set;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.JoinTable;
+import jakarta.persistence.ManyToMany;
+import jakarta.persistence.Table;
+
+@Entity
+@Table(name = "guardrail")
+public class Guardrail {
+
+  @Id @GeneratedValue public Long id;
+
+  public String name;
+
+  public String description;
+
+  @Enumerated(EnumType.STRING)
+  public GuardrailScope scope;
+
+  @ManyToMany(fetch = FetchType.EAGER)
+  @JoinTable(
+      name = "guardrail_metrics",
+      joinColumns = @JoinColumn(name = "guardrail_id"),
+      inverseJoinColumns = @JoinColumn(name = "task_metric_id"))
+  public Set<TaskMetric> metrics;
+
+  @Column(name = "external_references")
+  public List<String> references;
+
+  @Column(name = "metadata_keys")
+  public List<String> metadataKeys;
+
+  @Column(name = "instructions")
+  public String instructions;
+}

src/main/java/com/redhat/exhort/model/modelcards/GuardrailScope.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 Red Hat, Inc. and/or its affiliates
+ * and other contributors as indicated by the @author tags.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.redhat.exhort.model.modelcards;
+
+public enum GuardrailScope {
+  INPUT,
+  OUTPUT,
+  BOTH;
+}

src/main/java/com/redhat/exhort/modelcards/GuardrailRepository.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 Red Hat, Inc. and/or its affiliates
+ * and other contributors as indicated by the @author tags.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.redhat.exhort.modelcards;
+
+import java.util.List;
+
+import com.redhat.exhort.model.modelcards.Guardrail;
+
+import io.quarkus.hibernate.orm.panache.PanacheRepository;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class GuardrailRepository implements PanacheRepository<Guardrail> {
+
+  public List<Guardrail> findByTaskMetricIds(List<Long> taskMetricIds) {
+    return list(
+        "SELECT DISTINCT g FROM Guardrail g JOIN g.metrics m WHERE m.id IN ?1", taskMetricIds);
+  }
+}

src/main/java/com/redhat/exhort/modelcards/ModelCardService.java

@@ -18,6 +18,7 @@
 
 package com.redhat.exhort.modelcards;
 
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -33,6 +34,7 @@
 import com.redhat.exhort.api.v4.ReportConfig;
 import com.redhat.exhort.api.v4.ReportMetric;
 import com.redhat.exhort.api.v4.ReportTask;
+import com.redhat.exhort.model.modelcards.Guardrail;
 import com.redhat.exhort.model.modelcards.ModelCardConfig;
 import com.redhat.exhort.model.modelcards.ModelCardReport;
 import com.redhat.exhort.model.modelcards.ModelCardTask;
@@ -48,13 +50,30 @@ public class ModelCardService {
 
   @Inject ModelCardRepository repository;
 
+  @Inject GuardrailRepository guardrailRepository;
+
   @Transactional
   public ModelCardResponse get(UUID id) {
     var report = repository.findById(id);
     if (report == null) {
       return null;
     }
-    return toDto(report);
+    List<Guardrail> guardrails = new ArrayList<>();
+    if (report.tasks != null) {
+      // Extract task metric IDs from the scores map
+      List<Long> taskMetricIds =
+          report.tasks.stream()
+              .flatMap(task -> task.scores.keySet().stream())
+              .map(metric -> metric.id)
+              .distinct()
+              .toList();
+
+      if (!taskMetricIds.isEmpty()) {
+        guardrails = guardrailRepository.findByTaskMetricIds(taskMetricIds);
+      }
+    }
+
+    return toDto(report, guardrails);
   }
 
   @Transactional
@@ -70,13 +89,17 @@ public List<ListModelCardResponse> find(List<ModelCardQueryItem> queries) {
     return reports.stream().map(this::toSummaryDto).collect(Collectors.toList());
   }
 
-  private ModelCardResponse toDto(ModelCardReport entity) {
+  private ModelCardResponse toDto(ModelCardReport entity, List<Guardrail> guardrails) {
     var dto = new ModelCardResponse();
     dto.id(entity.id.toString());
     dto.name(entity.name);
     dto.source(entity.source);
     dto.config(toConfigDto(entity.config));
-    dto.tasks(entity.tasks != null ? entity.tasks.stream().map(this::toTaskDto).toList() : null);
+    dto.tasks(
+        entity.tasks != null
+            ? entity.tasks.stream().map(t -> toTaskDto(t, guardrails)).toList()
+            : null);
+    dto.guardrails(guardrails.stream().map(this::toGuardrailDto).toList());
     return dto;
   }
 
@@ -96,21 +119,23 @@ private ReportConfig toConfigDto(ModelCardConfig entity) {
     return dto;
   }
 
-  private ReportTask toTaskDto(ModelCardTask entity) {
+  private ReportTask toTaskDto(ModelCardTask entity, List<Guardrail> guardrails) {
     if (entity == null) return null;
 
     var dto = new ReportTask();
     dto.name(entity.task.name);
     dto.description(entity.task.description);
     dto.tags(List.copyOf(entity.task.tags));
-
     dto.metrics(
-        entity.scores.entrySet().stream().map(this::toMetricScoreDto).collect(Collectors.toList()));
+        entity.scores.entrySet().stream()
+            .map(s -> toMetricScoreDto(s, guardrails))
+            .collect(Collectors.toList()));
 
     return dto;
   }
 
-  private ReportMetric toMetricScoreDto(Map.Entry<TaskMetric, Float> e) {
+  private ReportMetric toMetricScoreDto(
+      Map.Entry<TaskMetric, Float> e, List<Guardrail> guardrails) {
     var score = new ReportMetric();
     score.name(e.getKey().name);
     score.score(e.getValue());
@@ -119,6 +144,13 @@ private ReportMetric toMetricScoreDto(Map.Entry<TaskMetric, Float> e) {
         e.getKey().thresholds != null
             ? e.getKey().thresholds.stream().map(this::toThresholdDto).toList()
             : null);
+    var metricGuardrails =
+        guardrails.stream()
+            .filter(g -> g.metrics.contains(e.getKey()))
+            .map(g -> g.id)
+            .sorted()
+            .toList();
+    score.guardrails(metricGuardrails);
     score.categories(List.copyOf(e.getKey().categories));
     return score;
   }
@@ -168,4 +200,16 @@ private String getAssessment(List<Threshold> thresholds, Float score) {
     }
     return null;
   }
+
+  private com.redhat.exhort.api.v4.Guardrail toGuardrailDto(Guardrail entity) {
+    var dto = new com.redhat.exhort.api.v4.Guardrail();
+    dto.id(entity.id);
+    dto.name(entity.name);
+    dto.description(entity.description);
+    dto.scope(com.redhat.exhort.api.v4.Guardrail.ScopeEnum.valueOf(entity.scope.name()));
+    dto.externalReferences(entity.references);
+    dto.metadataKeys(entity.metadataKeys);
+    dto.instructions(entity.instructions);
+    return dto;
+  }
 }

src/main/resources/db/README.md

@@ -7,6 +7,8 @@ This directory contains SQL scripts for setting up the Model Card database schem
 - `V1__create_model_card_tables.sql` - Creates the database tables for Model Card entities
 - `V2__insert_base_data.sql` - Inserts initial configuration data for Tasks and Thresholds
 - `V3__insert_report_data.sql` - Inserts data from the available reports existing at the moment 
+- `V4__create_guardrail_tables.sql` - Creates the database tables for Guardrail entities
+- `V5__inert_guardrail_data.sql` - Inserts Guardrail data for 4 initial recommendations
 
 ## Table Structure
 

src/main/resources/db/migration/V4__create_guardrail_tables.sql

@@ -0,0 +1,33 @@
+-- Create tables for Guardrail entity
+
+-- Guardrail table
+CREATE TABLE guardrail (
+    id BIGSERIAL PRIMARY KEY,
+    name VARCHAR(255),
+    description TEXT,
+    scope VARCHAR(255),
+    external_references VARCHAR(255)[],
+    metadata_keys VARCHAR(255)[],
+    instructions TEXT
+);
+
+-- Guardrail Metrics join table
+CREATE TABLE guardrail_metrics (
+    guardrail_id BIGINT NOT NULL,
+    task_metric_id BIGINT NOT NULL,
+    PRIMARY KEY (guardrail_id, task_metric_id),
+    FOREIGN KEY (guardrail_id) REFERENCES guardrail(id) ON DELETE CASCADE,
+    FOREIGN KEY (task_metric_id) REFERENCES task_metric(id) ON DELETE CASCADE
+);
+
+-- Create explicit sequence to match Hibernate's naming expectations
+CREATE SEQUENCE guardrail_SEQ START WITH 1 INCREMENT BY 50;
+
+-- Update table to use explicit sequence
+ALTER TABLE guardrail ALTER COLUMN id SET DEFAULT nextval('guardrail_SEQ');
+
+-- Create indexes for better performance
+CREATE INDEX idx_guardrail_name ON guardrail(name);
+CREATE INDEX idx_guardrail_scope ON guardrail(scope);
+CREATE INDEX idx_guardrail_metrics_guardrail_id ON guardrail_metrics(guardrail_id);
+CREATE INDEX idx_guardrail_metrics_task_metric_id ON guardrail_metrics(task_metric_id);