Merge branch 'evals' of https://github.com/buster-so/buster into evals

api/libs/agents/src/tools/categories/file_tools/common.rs

@@ -169,6 +169,22 @@ properties:
     description: "Human-readable time period covered by the query (e.g., 'Last 30 days', 'All time', 'August 1, 2024 - January 1, 2025', 'Comparison: August 2025 to August 2024')"
 
   # SQL QUERY
+  ### SQL Best Practices and Constraints** (when creating new metrics)  
+  #  - **Constraints**: Only join tables with explicit entity relationships.  
+  #  - **SQL Requirements**:  
+  #    - Use schema-qualified table names (`<SCHEMA_NAME>.<TABLE_NAME>`).  
+  #    - Select specific columns (avoid `SELECT *` or `COUNT(*)`).  
+  #    - Use CTEs instead of subqueries, and use snake_case for naming them.  
+  #    - Use `DISTINCT` (not `DISTINCT ON`) with matching `GROUP BY`/`SORT BY` clauses.  
+  #    - Show entity names rather than just IDs.  
+  #    - Handle date conversions appropriately.  
+  #    - Order dates in ascending order.
+  #    - Reference database identifiers for cross-database queries.  
+  #    - Format output for the specified visualization type.  
+  #    - Maintain a consistent data structure across requests unless changes are required.  
+  #    - Use explicit ordering for custom buckets or categories.
+  #    - When grouping metrics by dates, default to monthly granularity for spans over 2 months, yearly for over 3 years, weekly for under 2 months, and daily for under a week, unless the user specifies a different granularity.
+  ###
   sql:
     type: string
     description: "SQL query using YAML pipe syntax (|)"

api/libs/agents/src/tools/categories/planning_tools/create_plan.rs

@@ -229,5 +229,21 @@ Use this checklist to select the most appropriate Analysis Type:
 - Justify each chart's value to the objective.
 - Confirm feasibility with available data.
 
+### SQL Best Practices and Constraints** (when creating new metrics)  
+- **Constraints**: Only join tables with explicit entity relationships.  
+- **SQL Requirements**:  
+  - Use schema-qualified table names (`<SCHEMA_NAME>.<TABLE_NAME>`).  
+  - Select specific columns (avoid `SELECT *` or `COUNT(*)`).  
+  - Use CTEs instead of subqueries, and use snake_case for naming them.  
+  - Use `DISTINCT` (not `DISTINCT ON`) with matching `GROUP BY`/`SORT BY` clauses.  
+  - Show entity names rather than just IDs.  
+  - Handle date conversions appropriately.  
+  - Order dates in ascending order.
+  - Reference database identifiers for cross-database queries.  
+  - Format output for the specified visualization type.  
+  - Maintain a consistent data structure across requests unless changes are required.  
+  - Use explicit ordering for custom buckets or categories.
+  - When grouping metrics by dates, default to monthly granularity for spans over 2 months, yearly for over 3 years, weekly for under 2 months, and daily for under a week, unless the user specifies a different granularity.
+
 ---
 "##;