feat (expression): Experimental support for expression based filtering in model behavior. (#13)

next.config.js

@@ -22,7 +22,6 @@ const cspMap = {
   'base-uri': ["'none'"],
   'font-src': ["'self'", 'data:', "'unsafe-inline'"],
   'form-action': ["'self'"],
-  'frame-ancestors': ["'none'"],
   'frame-src': ["'self'"],
   'img-src': ["'self'", 'data:', 'blob:', 'www.ibm.com/'],
   'media-src': ["'self'", 'blob:', 'www.ibm.com/'],

src/components/expression-builder/ExpressionBuilder.module.scss

@@ -0,0 +1,40 @@
+/**
+ *
+ * Copyright 2023-2024 InspectorRAGet Team
+ *
+ * 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.
+ *
+ **/
+
+@use '@carbon/react/scss/spacing' as *;
+@use '@carbon/colors' as *;
+
+.page {
+  display: flex;
+  flex-direction: column;
+}
+
+.actionButtons {
+  margin: $spacing-03 0;
+  display: flex;
+  column-gap: $spacing-03;
+}
+
+.containerWarning {
+  display: flex;
+  column-gap: $spacing-03;
+  align-items: center;
+  color: var(--cds-support-warning);
+  font-size: 14px;
+  line-height: 16px;
+}

src/components/expression-builder/ExpressionBuilder.tsx

@@ -0,0 +1,143 @@
+/**
+ *
+ * Copyright 2023-2024 InspectorRAGet Team
+ *
+ * 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.
+ *
+ **/
+
+'use client';
+
+import { isEmpty } from 'lodash';
+import { useState, useEffect } from 'react';
+import { TextArea, Button } from '@carbon/react';
+import { WarningAlt } from '@carbon/icons-react';
+
+import { Model, Metric } from '@/src/types';
+import {
+  PLACHOLDER_EXPRESSION_TEXT,
+  validate,
+} from '@/src/utilities/expressions';
+
+import classes from './ExpressionBuilder.module.scss';
+
+// ===================================================================================
+//                                TYPES
+// ===================================================================================
+interface Props {
+  expression?: object;
+  models?: Model[];
+  metric?: Metric;
+  setExpression?: Function;
+}
+
+// ===================================================================================
+//                               MAIN FUNCTION
+// ===================================================================================
+export default function ExpressionBuilder({
+  expression,
+  models,
+  metric,
+  setExpression,
+}: Props) {
+  // Step 1: Initialize state and necessary variables
+  const [updatedExpressionText, setUpdatedExpressionText] = useState<string>(
+    expression ? JSON.stringify(expression) : PLACHOLDER_EXPRESSION_TEXT,
+  );
+  const [errorMessage, setErrorMessage] = useState<string>();
+
+  // Step 2: Run effects
+  // Step 2.a: Validate expression when updated
+  useEffect(() => {
+    try {
+      // Step 2.a: Check JSON validity
+      const updatedExpression = JSON.parse(updatedExpressionText);
+
+      // Step 2.b: Check expression validity
+      const errorMessage = validate(
+        updatedExpression,
+        models?.map((model) => model.modelId),
+      );
+      if (errorMessage) {
+        setErrorMessage(errorMessage);
+      } else {
+        setErrorMessage(undefined);
+      }
+    } catch (err) {
+      setErrorMessage('Invalid JSON');
+    }
+  }, [updatedExpressionText]);
+
+  return (
+    <div className={classes.page}>
+      <TextArea
+        labelText="Expression"
+        placeholder={JSON.stringify(expression)}
+        value={updatedExpressionText}
+        disabled={
+          models === undefined ||
+          metric === undefined ||
+          setExpression === undefined
+        }
+        invalid={errorMessage !== undefined}
+        invalidText={errorMessage}
+        onChange={(event) => {
+          setUpdatedExpressionText(event.target.value);
+        }}
+        helperText="Please make sure you select correct model ids and values"
+        rows={4}
+        id="text-area__expression"
+      />
+      <div className={classes.actionButtons}>
+        <Button
+          kind="primary"
+          disabled={
+            errorMessage !== undefined ||
+            models === undefined ||
+            metric === undefined ||
+            setExpression === undefined
+          }
+          onClick={() =>
+            setExpression
+              ? setExpression(JSON.parse(updatedExpressionText))
+              : () => {}
+          }
+        >
+          Run
+        </Button>
+        <Button
+          kind="secondary"
+          disabled={expression === undefined || isEmpty(expression)}
+          onClick={() => {
+            // Step 1: Reset updated expression text
+            setUpdatedExpressionText('{}');
+
+            // Step 2: Reset expression
+            if (setExpression) {
+              setExpression({});
+            }
+          }}
+        >
+          Clear
+        </Button>
+      </div>
+
+      {models === undefined || metric === undefined ? (
+        <div className={classes.containerWarning}>
+          <WarningAlt />
+          <span>You must select a metric before proceeding.</span>
+        </div>
+      ) : null}
+    </div>
+  );
+}

src/components/filters/Filters.module.scss

@@ -43,17 +43,22 @@
   align-items: center;
 }
 
-.filters {
+.container {
   margin: 0 0 $spacing-03 $spacing-05;
-  padding: $spacing-05;
   display: none;
+  box-shadow: 0 0 5px 2px $gray-40;
+}
+
+.filters {
+  padding: $spacing-05;
+  display: flex;
   align-items: baseline;
   column-gap: $spacing-09;
-  box-shadow: 0 0 5px 2px $gray-40;
 }
 
 .visible {
   display: flex;
+  flex-direction: column;
   animation: fade-in 0.5s;
 }
 

src/components/filters/Filters.tsx

@@ -22,10 +22,22 @@ import { isEmpty, omit } from 'lodash';
 import cx from 'classnames';
 import { useState, useEffect } from 'react';
 
-import { FilterableMultiSelect, Tag, Tooltip, Button } from '@carbon/react';
+import {
+  FilterableMultiSelect,
+  Tag,
+  Tooltip,
+  Button,
+  Tabs,
+  TabList,
+  Tab,
+  TabPanels,
+  TabPanel,
+} from '@carbon/react';
 import { ChevronUp, ChevronDown, Filter } from '@carbon/icons-react';
+import ExpressionBuilder from '@/src/components/expression-builder/ExpressionBuilder';
 
 import classes from './Filters.module.scss';
+import { Metric, Model } from '@/src/types';
 
 // ===================================================================================
 //                                TYPES
@@ -35,6 +47,10 @@ interface Props {
   filters: { [key: string]: string[] };
   selectedFilters: { [key: string]: string[] };
   setSelectedFilters: Function;
+  models?: Model[];
+  metric?: Metric;
+  expression?: object;
+  setExpression?: Function;
 }
 
 // ===================================================================================
@@ -45,6 +61,10 @@ export default function Filters({
   filters,
   selectedFilters,
   setSelectedFilters,
+  models,
+  metric,
+  expression,
+  setExpression,
 }: Props) {
   // Step 1: Initialize state and necessary variables
   const [showFilters, setShowFilters] = useState<boolean>(true);
@@ -52,7 +72,7 @@ export default function Filters({
   // Step 2: Run effects
   // Step 2.a: If no filters are found, set show filters to false
   useEffect(() => {
-    if (filters === undefined) {
+    if (filters === undefined && setExpression === undefined) {
       setShowFilters(false);
     }
   }, [filters]);
@@ -90,48 +110,123 @@ export default function Filters({
           </Button>
         </Tooltip>
       )}
-      <div className={cx(classes.filters, showFilters && classes.visible)}>
-        {showFilters &&
-          filters &&
-          Object.entries(filters).map(([filterType, values]) => {
-            return (
-              <div
-                key={`${keyPrefix}-filter` + filterType + '-selector'}
-                className={classes.filterSelector}
-              >
-                <FilterableMultiSelect
-                  id={`${keyPrefix}-filter` + filterType + '-selector'}
-                  titleText={filterType}
-                  items={values}
-                  itemToString={(item) => String(item)}
-                  onChange={(event) => {
-                    setSelectedFilters((prevState) =>
-                      isEmpty(event.selectedItems)
-                        ? omit(prevState, filterType)
-                        : {
-                            ...prevState,
-                            [filterType]: event.selectedItems,
-                          },
-                    );
-                  }}
-                ></FilterableMultiSelect>
-                {Object.keys(selectedFilters).includes(filterType) ? (
-                  <div>
-                    {selectedFilters[filterType].map((value) => {
+      <div className={cx(classes.container, showFilters && classes.visible)}>
+        {showFilters ? (
+          filters && expression ? (
+            <Tabs>
+              <TabList aria-label="additional filters" contained fullWidth>
+                <Tab>Static</Tab>
+                <Tab>
+                  Expression <Tag type="green">Experimental</Tag>
+                </Tab>
+              </TabList>
+              <TabPanels>
+                <TabPanel>
+                  <div className={classes.filters}>
+                    {Object.entries(filters).map(([filterType, values]) => {
                       return (
-                        <Tag
-                          type={'cool-gray'}
-                          key={`${keyPrefix}-filter-value` + value}
+                        <div
+                          key={`${keyPrefix}-filter` + filterType + '-selector'}
+                          className={classes.filterSelector}
                         >
-                          {value}
-                        </Tag>
+                          <FilterableMultiSelect
+                            id={
+                              `${keyPrefix}-filter` + filterType + '-selector'
+                            }
+                            titleText={filterType}
+                            items={values}
+                            itemToString={(item) => String(item)}
+                            onChange={(event) => {
+                              setSelectedFilters((prevState) =>
+                                isEmpty(event.selectedItems)
+                                  ? omit(prevState, filterType)
+                                  : {
+                                      ...prevState,
+                                      [filterType]: event.selectedItems,
+                                    },
+                              );
+                            }}
+                          ></FilterableMultiSelect>
+                          {Object.keys(selectedFilters).includes(filterType) ? (
+                            <div>
+                              {selectedFilters[filterType].map((value) => {
+                                return (
+                                  <Tag
+                                    type={'cool-gray'}
+                                    key={`${keyPrefix}-filter-value` + value}
+                                  >
+                                    {value}
+                                  </Tag>
+                                );
+                              })}
+                            </div>
+                          ) : null}
+                        </div>
                       );
                     })}
                   </div>
-                ) : null}
-              </div>
-            );
-          })}
+                </TabPanel>
+                <TabPanel>
+                  <ExpressionBuilder
+                    expression={expression}
+                    models={models}
+                    metric={metric}
+                    setExpression={setExpression}
+                  ></ExpressionBuilder>
+                </TabPanel>
+              </TabPanels>
+            </Tabs>
+          ) : filters ? (
+            <div className={classes.filters}>
+              {Object.entries(filters).map(([filterType, values]) => {
+                return (
+                  <div
+                    key={`${keyPrefix}-filter` + filterType + '-selector'}
+                    className={classes.filterSelector}
+                  >
+                    <FilterableMultiSelect
+                      id={`${keyPrefix}-filter` + filterType + '-selector'}
+                      titleText={filterType}
+                      items={values}
+                      itemToString={(item) => String(item)}
+                      onChange={(event) => {
+                        setSelectedFilters((prevState) =>
+                          isEmpty(event.selectedItems)
+                            ? omit(prevState, filterType)
+                            : {
+                                ...prevState,
+                                [filterType]: event.selectedItems,
+                              },
+                        );
+                      }}
+                    ></FilterableMultiSelect>
+                    {Object.keys(selectedFilters).includes(filterType) ? (
+                      <div>
+                        {selectedFilters[filterType].map((value) => {
+                          return (
+                            <Tag
+                              type={'cool-gray'}
+                              key={`${keyPrefix}-filter-value` + value}
+                            >
+                              {value}
+                            </Tag>
+                          );
+                        })}
+                      </div>
+                    ) : null}
+                  </div>
+                );
+              })}
+            </div>
+          ) : expression ? (
+            <ExpressionBuilder
+              expression={expression}
+              models={models}
+              metric={metric}
+              setExpression={setExpression}
+            ></ExpressionBuilder>
+          ) : null
+        ) : null}
       </div>
     </>
   );

src/utilities/expressions.ts

@@ -0,0 +1,340 @@
+/**
+ *
+ * Copyright 2023-2024 InspectorRAGet Team
+ *
+ * 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.
+ *
+ **/
+
+import { isEmpty, intersectionWith, unionWith, isEqual } from 'lodash';
+import { Metric, TaskEvaluation } from '@/src/types';
+import { castToNumber } from '@/src/utilities/metrics';
+
+// ===================================================================================
+//                                CONSTANTS
+// ===================================================================================
+export const PLACHOLDER_EXPRESSION_TEXT = '{}';
+export enum EXPRESSION_OPERATORS {
+  // Logical operators
+  AND = '$and',
+  OR = '$or',
+
+  // Comparison operators
+  EQ = '$eq',
+  NEQ = '$neq',
+  GT = '$gt',
+  GTE = '$gte',
+  LT = '$lt',
+  LTE = '$lte',
+}
+
+export function validate(
+  expression: object,
+  modelIds?: string[],
+  values?: (string | number)[],
+  parent?: string,
+): string | null {
+  // Step 1: Identify all the keys
+  const keys = Object.keys(expression);
+
+  // Step 2: In case of operator presence
+  const operators = keys.filter((key) => key.startsWith('$'));
+  if (operators.length > 1) {
+    return `More than one operator [${operators.join(', ')}] on the same level in the expression`;
+  }
+
+  if (operators.length === 1 && keys.length > 1) {
+    return `Additional keys on the same level in the expression`;
+  }
+
+  if (operators.length === 1) {
+    const operator = operators[0];
+
+    // Logical operator condition
+    if (
+      operator === EXPRESSION_OPERATORS.AND ||
+      operator === EXPRESSION_OPERATORS.OR
+    ) {
+      if (parent && modelIds && modelIds.includes(parent)) {
+        return `Logical operator ("${operator}") must not preceed with model ID`;
+      }
+
+      if (
+        !Array.isArray(expression[operator]) ||
+        expression[operator].some((value) => typeof value !== 'object')
+      ) {
+        return `Logical operator ("${operator}") must follow with array of expressions`;
+      }
+
+      if (
+        isEmpty(expression[operator]) ||
+        expression[operator].some((entry) => isEmpty(entry))
+      ) {
+        return `Logical operator ("${operator}") cannot have empty expression value`;
+      }
+
+      for (let index = 0; index < expression[operator].length; index++) {
+        const nestedErrorMessage = validate(
+          expression[operator][index],
+          modelIds,
+        );
+        if (nestedErrorMessage) {
+          return nestedErrorMessage;
+        }
+      }
+    }
+    // Comparison operators condition
+    else if (
+      operator === EXPRESSION_OPERATORS.EQ ||
+      operator === EXPRESSION_OPERATORS.NEQ ||
+      operator === EXPRESSION_OPERATORS.LT ||
+      operator === EXPRESSION_OPERATORS.LTE ||
+      operator === EXPRESSION_OPERATORS.GT ||
+      operator === EXPRESSION_OPERATORS.GTE
+    ) {
+      if (parent === undefined || parent.startsWith('$')) {
+        return `Comparison operator ("${operator}") must preceed with model ID`;
+      }
+      if (
+        typeof expression[operator] !== 'string' &&
+        typeof expression[operator] !== 'number'
+      ) {
+        return `Comparison operator ("${operator}") must follow primitive data types ("string" or "number")`;
+      }
+    }
+  } else {
+    // Step 3: In case of operator less expression
+    for (let idx = 0; idx < keys.length; idx++) {
+      // Step 3.a: If model IDs are provided, make sure key is one of those model IDs
+      if (modelIds && !modelIds.includes(keys[idx])) {
+        return `Model ("${keys[idx]}") does not exists. Please use one for the following models: ${modelIds.join(', ')}`;
+      }
+
+      const value = expression[keys[idx]];
+      if (
+        typeof value !== 'object' &&
+        typeof value !== 'string' &&
+        typeof value !== 'number'
+      ) {
+        return `Model ("${keys[idx]}") must follow either expression or primitive data types ("string" or "number")`;
+      }
+
+      if (typeof value === 'object') {
+        const nestedErrorMessage = validate(
+          expression[keys[idx]],
+          modelIds,
+          values,
+          keys[idx],
+        );
+        if (nestedErrorMessage) {
+          return nestedErrorMessage;
+        }
+      } else {
+        if (values && !values.includes(value)) {
+          return `"${value}" is not a valid value option. Please use one of the following: ${values.join(', ')}`;
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+export function evaluate(
+  evaluationsPerTaskPerModel: {
+    [key: string]: { [key: string]: TaskEvaluation };
+  },
+  expression: object,
+  metric: Metric,
+  annotator?: string,
+): TaskEvaluation[] {
+  // Step 1: Initialize necessary variables
+  const eligibleEvaluations: TaskEvaluation[] = [];
+
+  // Step 2: Identify all the keys
+  const keys = Object.keys(expression);
+
+  // Step 3: In case of operator presence
+  const operators = keys.filter((key) => key.startsWith('$'));
+  if (operators.length === 1) {
+    const operator = operators[0];
+
+    // Step 3.a: In case of a logical operator
+    if (
+      operator === EXPRESSION_OPERATORS.AND ||
+      operator === EXPRESSION_OPERATORS.OR
+    ) {
+      // Step 3.a.i: Initialize necessary variables
+      const results: TaskEvaluation[][] = [];
+
+      // Step 3.a.ii: Identify evaluations meeting nested expression
+      expression[operator].forEach((condition) => {
+        results.push(
+          evaluate(evaluationsPerTaskPerModel, condition, metric, annotator),
+        );
+      });
+
+      // Step 3.a.iii: Apply intersection ('$and') or union ('$or') logic based on the logical operator
+      if (operator === EXPRESSION_OPERATORS.AND) {
+        return intersectionWith(...results, isEqual);
+      } else {
+        return unionWith(...results, isEqual);
+      }
+    }
+  } else {
+    // Step 3: In case of expression without logical operators
+    // Step 3.a: Iterate over evaluations for each task
+    Object.values(evaluationsPerTaskPerModel).forEach((evaluationPerModel) => {
+      // Step 3.a.i: Initialize necessary variables
+      let satisfy: boolean = true;
+
+      // Step 3.a.ii: Iterate over conditions for each model in the expression
+      for (let idx = 0; idx < keys.length; idx++) {
+        // Step 3.a.ii.*: Check if evaluation exists
+        if (!evaluationPerModel.hasOwnProperty(keys[idx])) {
+          satisfy = false;
+          break;
+        }
+
+        // Step 3.a.ii.**: Fetch evaluation, value and expected value condition
+        const evaluation = evaluationPerModel[keys[idx]];
+
+        // Step 3.a.ii.***: Calculate value
+        /**
+         * annotator specific value if annotator is specified
+         * OR
+         * aggregate value
+         */
+        let value: string | number;
+        if (annotator) {
+          if (!evaluation[metric.name].hasOwnProperty(annotator)) {
+            satisfy = false;
+            break;
+          }
+          value = castToNumber(
+            evaluation[metric.name][annotator].value,
+            metric.values,
+          );
+        } else {
+          value = castToNumber(
+            evaluation[`${metric.name}_agg`].value,
+            metric.values,
+          );
+        }
+
+        // Step 3.a.ii.*****: Extract expection from expression
+        const expectation = expression[keys[idx]];
+
+        // Step 3.a.ii.******: In case of expectation is an expression
+        if (typeof expectation === 'object') {
+          // Extract comparison operator from expectation expression
+          const operator = Object.keys(expectation).filter((key) =>
+            key.startsWith('$'),
+          )[0];
+
+          // If comparison operator is "$gt" OR "$gte"
+          if (
+            (operator === EXPRESSION_OPERATORS.GTE ||
+              operator === EXPRESSION_OPERATORS.GT) &&
+            (isNaN(value) ||
+              value <
+                castToNumber(
+                  expectation[operator],
+                  metric.values,
+                  typeof expectation[operator] === 'string'
+                    ? 'displayValue'
+                    : 'value',
+                ))
+          ) {
+            satisfy = false;
+            break;
+          }
+
+          // If comparison operator is "$lt" OR "$lte"
+          if (
+            (operator === EXPRESSION_OPERATORS.LTE ||
+              operator === EXPRESSION_OPERATORS.LT) &&
+            (isNaN(value) ||
+              value >
+                castToNumber(
+                  expectation[operator],
+                  metric.values,
+                  typeof expectation[operator] === 'string'
+                    ? 'displayValue'
+                    : 'value',
+                ))
+          ) {
+            satisfy = false;
+            break;
+          }
+
+          // If comparison operator is "$eq"
+          if (
+            operator === EXPRESSION_OPERATORS.EQ &&
+            (isNaN(value) ||
+              value !==
+                castToNumber(
+                  expectation[operator],
+                  metric.values,
+                  typeof expectation[operator] === 'string'
+                    ? 'displayValue'
+                    : 'value',
+                ))
+          ) {
+            satisfy = false;
+            break;
+          }
+
+          // If comparison operator is "$neq"
+          if (
+            operator === EXPRESSION_OPERATORS.NEQ &&
+            (isNaN(value) ||
+              value ===
+                castToNumber(
+                  expectation[operator],
+                  metric.values,
+                  typeof expectation[operator] === 'string'
+                    ? 'displayValue'
+                    : 'value',
+                ))
+          ) {
+            satisfy = false;
+            break;
+          }
+        } else {
+          // 3.a.ii.******: In case of expectation is a primitive type ("string"/"number") value
+          if (
+            isNaN(value) ||
+            value !==
+              castToNumber(
+                expectation,
+                metric.values,
+                typeof expectation === 'string' ? 'displayValue' : 'value',
+              )
+          ) {
+            satisfy = false;
+            break;
+          }
+        }
+      }
+
+      // Step 3.a.iii: If satisfy expression requirments, add all evaluations for the current task to eligible evaluations list
+      if (satisfy) {
+        eligibleEvaluations.push(...Object.values(evaluationPerModel));
+      }
+    });
+  }
+
+  // Step 4: Return
+  return eligibleEvaluations;
+}

src/utilities/metrics.ts

@@ -80,13 +80,16 @@ export function extractMetricDisplayName(metric: Metric): string {
 export function castToNumber(
   value: string | number,
   references?: MetricValue[],
+  key?: 'value' | 'displayValue',
 ): number {
   // If value is of type "string"
   if (typeof value === 'string') {
     // Step 1: Check if references are provided to convert "string" value to "numeric" value
     if (references) {
       // Step 1.a: Find appropriate reference by comparing "string" values
-      const reference = references.find((entry) => entry.value === value);
+      const reference = references.find((entry) =>
+        key ? entry[key] === value : entry.value === value,
+      );
 
       // Step 1.b: If numeric value exists in reference, then return it
       if (
@@ -96,7 +99,7 @@ export function castToNumber(
       ) {
         return reference.numericValue;
       } else {
-        return parseInt(value);
+        return parseFloat(value);
       }
     }
     // Step 2: Cast to int, if references are absent

src/views/model-behavior/ModelBehavior.tsx

@@ -18,7 +18,7 @@
 
 'use client';
 
-import { isEmpty, omit } from 'lodash';
+import { isEmpty } from 'lodash';
 import Link from 'next/link';
 import cx from 'classnames';
 import { useState, useMemo, useEffect } from 'react';
@@ -56,6 +56,7 @@ import {
 } from '@/src/utilities/metrics';
 import { areObjectsIntersecting } from '@/src/utilities/objects';
 import { getModelColorPalette } from '@/src/utilities/colors';
+import { evaluate } from '@/src/utilities/expressions';
 import TasksTable from '@/src/views/tasks-table/TasksTable';
 import MetricSelector from '@/src/components/selectors/MetricSelector';
 import Filters from '@/src/components/filters/Filters';
@@ -158,14 +159,17 @@ function process(
   selectedAllowedValues: string[],
   selectedAnnotator: string | undefined,
   filters: { [key: string]: string[] },
+  expression?: object,
 ): [(record & { [key: string]: string | number })[], TaskEvaluation[]] {
+  // Step 1: Initialize necessary variables
   const models = selectedModels.reduce(
     (obj, item) => ((obj[item.modelId] = item), obj),
     {},
   );
   const records: (record & { [key: string]: string | number })[] = [];
-  const filteredEvaluations: TaskEvaluation[] = [];
-  // apply filters
+  const visibleEvaluations: TaskEvaluation[] = [];
+
+  // Step 2: If filters are specified
   const filteredEvaluationsPerMetric: { [key: string]: TaskEvaluation[] } = {};
   for (const [metric, evals] of Object.entries(evaluationsPerMetric)) {
     filteredEvaluationsPerMetric[metric] = !isEmpty(filters)
@@ -173,66 +177,115 @@ function process(
       : evals;
   }
 
+  // Step 3: If a metric is selected
   if (selectedMetric) {
-    filteredEvaluationsPerMetric[selectedMetric.name].forEach((evaluation) => {
-      // If individual annotator is selected
-      if (selectedAnnotator) {
-        /**
-         * Evaluation's model id fall within selected models
-         * OR
-         * Evaluation's selected metric's value fall within allowed values
-         */
-        if (
-          evaluation.modelId in models &&
-          evaluation[selectedMetric.name].hasOwnProperty(selectedAnnotator) &&
-          (!selectedAllowedValues.length ||
-            selectedAllowedValues.includes(
-              evaluation[selectedMetric.name][selectedAnnotator].value,
-            ))
-        ) {
-          // Create and add record
-          records.push({
-            taskId: evaluation.taskId,
-            modelName: models[evaluation.modelId].name,
-            [`${selectedMetric.name}_value`]:
-              evaluation[selectedMetric.name][selectedAnnotator].value,
-          });
-
-          // Add evaluation
-          filteredEvaluations.push(evaluation);
-        }
-      } else {
-        if (
-          evaluation.modelId in models &&
-          selectedAgreementLevels
-            .map((level) => level.value)
-            .includes(evaluation[`${selectedMetric.name}_agg`].level) &&
-          (!selectedAllowedValues.length ||
-            selectedAllowedValues.includes(
-              evaluation[`${selectedMetric.name}_agg`].value,
-            ))
-        ) {
-          // Create and add record
-          records.push({
-            taskId: evaluation.taskId,
-            modelName: models[evaluation.modelId].name,
-            [`${selectedMetric.name}_value`]:
-              evaluation[`${selectedMetric.name}_agg`].value,
-            [`${selectedMetric.name}_aggLevel`]:
-              evaluation[`${selectedMetric.name}_agg`].level,
-          });
-
-          // Add evaluation
-          filteredEvaluations.push(evaluation);
-        }
-      }
-    });
+    // Step 3.a: If an expression is specified
+    if (expression && !isEmpty(expression)) {
+      // Step 3.a.ii: Build an object containing evaluations per model for every task
+      const evaluationsPerTaskPerModel: {
+        [key: string]: { [key: string]: TaskEvaluation };
+      } = {};
+      filteredEvaluationsPerMetric[selectedMetric.name].forEach(
+        (evaluation) => {
+          if (evaluationsPerTaskPerModel.hasOwnProperty(evaluation.taskId)) {
+            evaluationsPerTaskPerModel[evaluation.taskId][evaluation.modelId] =
+              evaluation;
+          } else {
+            evaluationsPerTaskPerModel[evaluation.taskId] = {
+              [evaluation.modelId]: evaluation,
+            };
+          }
+        },
+      );
+
+      // Step 3.a.iii: Find evaluations meeting expression criteria
+      evaluate(
+        evaluationsPerTaskPerModel,
+        expression,
+        selectedMetric,
+        selectedAnnotator,
+      ).forEach((evaluation) => {
+        // Step 3.a.iii.*: Create and add record
+        records.push({
+          taskId: evaluation.taskId,
+          modelName: models[evaluation.modelId].name,
+          [`${selectedMetric.name}_value`]:
+            evaluation[`${selectedMetric.name}_agg`].value,
+          [`${selectedMetric.name}_aggLevel`]:
+            evaluation[`${selectedMetric.name}_agg`].level,
+        });
+
+        // Step 3.a.iii.**: Add evaluation
+        visibleEvaluations.push(evaluation);
+      });
+    } else {
+      // Step 3.b: Filter evaluations for the selected metric
+      filteredEvaluationsPerMetric[selectedMetric.name].forEach(
+        (evaluation) => {
+          // Step 3.b.i: If individual annotator is selected, verify against annotator's value
+          if (selectedAnnotator) {
+            /**
+             * Evaluation's model id fall within selected models
+             * OR
+             * Evaluation's selected metric's value fall within allowed values
+             */
+            if (
+              evaluation.modelId in models &&
+              evaluation[selectedMetric.name].hasOwnProperty(
+                selectedAnnotator,
+              ) &&
+              (!selectedAllowedValues.length ||
+                selectedAllowedValues.includes(
+                  evaluation[selectedMetric.name][selectedAnnotator].value,
+                ))
+            ) {
+              // Step 3.b.i.*: Create and add record
+              records.push({
+                taskId: evaluation.taskId,
+                modelName: models[evaluation.modelId].name,
+                [`${selectedMetric.name}_value`]:
+                  evaluation[selectedMetric.name][selectedAnnotator].value,
+              });
+
+              // Step 3.b.i.**: Add evaluation
+              visibleEvaluations.push(evaluation);
+            }
+          } else {
+            // Step 3.b.ii: Verify against aggregate value
+            if (
+              evaluation.modelId in models &&
+              selectedAgreementLevels
+                .map((level) => level.value)
+                .includes(evaluation[`${selectedMetric.name}_agg`].level) &&
+              (!selectedAllowedValues.length ||
+                selectedAllowedValues.includes(
+                  evaluation[`${selectedMetric.name}_agg`].value,
+                ))
+            ) {
+              // Step 3.b.ii.*: Create and add record
+              records.push({
+                taskId: evaluation.taskId,
+                modelName: models[evaluation.modelId].name,
+                [`${selectedMetric.name}_value`]:
+                  evaluation[`${selectedMetric.name}_agg`].value,
+                [`${selectedMetric.name}_aggLevel`]:
+                  evaluation[`${selectedMetric.name}_agg`].level,
+              });
+
+              // Step 3.b.ii.**: Add evaluation
+              visibleEvaluations.push(evaluation);
+            }
+          }
+        },
+      );
+    }
   } else {
+    // Step 3: For every metric
     for (const [metric, evaluations] of Object.entries(
       filteredEvaluationsPerMetric,
     )) {
       evaluations.forEach((evaluation) => {
-        // If invidiual annotator is selected
+        // Step 3.a: If invidiual annotator is selected, verify against annotator's value
         if (selectedAnnotator) {
           /**
            * Evaluation's model id fall within selected models
@@ -254,6 +307,7 @@ function process(
             });
           }
         } else {
+          // Step 3.a: Verify against aggregate value
           if (
             evaluation.modelId in models &&
             selectedAgreementLevels
@@ -274,7 +328,7 @@ function process(
     }
   }
 
-  return [records, filteredEvaluations];
+  return [records, visibleEvaluations];
 }
 
 // ===================================================================================
@@ -318,6 +372,13 @@ export default function ModelBehavior({
     [key: string]: string[];
   }>({});
   const [modelColors, modelOrder] = getModelColorPalette(models);
+  const [expression, setExpression] = useState<object>({});
+  const [graphRecords, setGraphRecords] = useState<
+    (record & { [key: string]: string | number })[]
+  >([]);
+  const [visibleEvaluations, setVisibleEvaluations] = useState<
+    TaskEvaluation[]
+  >([]);
 
   // Step 2: Run effects
   // Step 2.a: Adjust graph width & heigh based on window size
@@ -358,7 +419,12 @@ export default function ModelBehavior({
     return annotatorsSet;
   }, [evaluationsPerMetric, metrics]);
 
-  // Step 2.d: Configure available majority values, if metric is selected
+  // Step 2.d: Reset expression, if selected metric changes
+  useEffect(() => {
+    setExpression({});
+  }, [selectedMetric]);
+
+  // Step 2.e: Configure available majority values, if metric is selected
   const availableAllowedValues = useMemo(() => {
     if (selectedMetric && selectedMetric.type === 'categorical') {
       if (selectedAnnotator) {
@@ -408,30 +474,20 @@ export default function ModelBehavior({
     selectedAgreementLevels,
   ]);
 
-  // Step 2.e: Update selected values list
+  // Step 2.f: Update selected values list
   useEffect(() => {
     setSelectedAllowedValues(availableAllowedValues);
   }, [availableAllowedValues]);
 
-  // Step 2.f: Calculate graph data and prepare visible evaluations list
+  // Step 2.g: Calculate graph data and prepare visible evaluations list
   /**
    * Adjust graph records based on selected agreement levels, models and annotator
    * visibleEvaluations : [{taskId: <>, modelId: <>, [metric]_score: <>}]
    * NOTE: * [metric]_score field avialable metrics (all OR single)
    *       * score field could be either majority score or individual annotator's score (based on selected annotator)
    */
-  const [graphRecords, visibleEvaluations] = useMemo(
-    () =>
-      process(
-        evaluationsPerMetric,
-        selectedAgreementLevels,
-        selectedModels,
-        selectedMetric,
-        selectedAllowedValues,
-        selectedAnnotator,
-        selectedFilters,
-      ),
-    [
+  useEffect(() => {
+    const [records, evaluations] = process(
       evaluationsPerMetric,
       selectedAgreementLevels,
       selectedModels,
@@ -439,10 +495,24 @@ export default function ModelBehavior({
       selectedAllowedValues,
       selectedAnnotator,
       selectedFilters,
-    ],
-  );
+      expression,
+    );
+
+    // Set graph records and visible evaluations
+    setGraphRecords(records);
+    setVisibleEvaluations(evaluations);
+  }, [
+    evaluationsPerMetric,
+    selectedAgreementLevels,
+    selectedModels,
+    selectedMetric,
+    selectedAllowedValues,
+    selectedAnnotator,
+    selectedFilters,
+    expression,
+  ]);
 
-  // Step 2.g: Calculate visible tasks per metric
+  // Step 2.h: Calculate visible tasks per metric
   const visibleTasksPerMetric = useMemo(() => {
     const data = {};
     metrics.forEach((metric) => {
@@ -458,7 +528,7 @@ export default function ModelBehavior({
     return data;
   }, [graphRecords, metrics]);
 
-  // Step 2.h: Buckets human and algoritmic metrics into individual buckets
+  // Step 2.i: Buckets human and algoritmic metrics into individual buckets
   const [humanMetrics, algorithmMetrics] = useMemo(() => {
     const hMetrics: Metric[] = [];
     const aMetrics: Metric[] = [];
@@ -648,6 +718,10 @@ export default function ModelBehavior({
           filters={filters}
           selectedFilters={selectedFilters}
           setSelectedFilters={setSelectedFilters}
+          models={selectedModels}
+          metric={selectedMetric}
+          expression={expression}
+          setExpression={setExpression}
         />
       ) : null}
 

src/views/tasks-table/TasksTable.tsx

@@ -343,7 +343,58 @@ export default function TasksTable({
     <>
       {headers && rows && (
         <div>
-          <DataTable rows={visibleRows} headers={headers} isSortable>
+          <DataTable
+            rows={visibleRows}
+            headers={headers}
+            isSortable
+            sortRow={(cellA, cellB, { sortDirection, sortStates }) => {
+              // Step 1: Check if cell values are objects
+              if (typeof cellA === 'object' && typeof cellB === 'object') {
+                // Step 1.a: Get first value for each cell object
+                const valueA = Object.values(cellA)[0];
+                const valueB = Object.values(cellB)[0];
+
+                // Step 1.b: Check if both values are of "string" type
+                if (typeof valueA === 'string' && typeof valueB === 'string') {
+                  // Step 1.b.i: Check if both values are purely numeric
+                  if (
+                    !isNaN(parseFloat(valueA)) &&
+                    !isNaN(parseFloat(valueB))
+                  ) {
+                    if (sortDirection === sortStates.DESC) {
+                      return parseFloat(valueA) - parseFloat(valueB);
+                    }
+                    return parseFloat(valueB) - parseFloat(valueA);
+                  } else {
+                    if (sortDirection === sortStates.DESC) {
+                      return valueA.localeCompare(valueB);
+                    }
+
+                    return valueB.localeCompare(valueA);
+                  }
+                }
+                // Step 1.c: Check if both values are of "number" type
+                else if (
+                  typeof valueA === 'number' &&
+                  typeof valueB === 'number'
+                ) {
+                  if (sortDirection === sortStates.DESC) {
+                    return valueA - valueB;
+                  }
+
+                  return valueB - valueA;
+                }
+              }
+              // Step 2: cell values are assumed to be of "string" type
+              else {
+                if (sortDirection === sortStates.DESC) {
+                  return cellA.localeCompare(cellB);
+                }
+
+                return cellB.localeCompare(cellA);
+              }
+            }}
+          >
             {({
               rows,
               headers,