add all files

ai_agents/db_agent/context/examples.json

@@ -0,0 +1,27 @@
+[
+  {
+    "question": "How many loads were completed yesterday?",
+  "sql": "SELECT COUNT(*) AS load_count\nFROM dbo.SugarLoadData\nWHERE DateOut >= CAST(DATEADD(day, -1, CAST(SYSDATETIME() AS date)) AS datetime)\n  AND DateOut < CAST(SYSDATETIME() AS date);",
+    "notes": "Uses DateOut to ensure the truck exited; bounds the window on the local date." 
+  },
+  {
+    "question": "Show the top 5 heaviest loads in the past week.",
+  "sql": "SELECT TOP (5) SugarLoadID_Pk, VehicleId_Fk, GrossWt, TareWt, Tons, DateOut\nFROM dbo.SugarLoadData\nWHERE DateOut >= DATEADD(day, -7, SYSDATETIME())\nORDER BY GrossWt DESC;",
+    "notes": "Ranks by gross weight; includes net/tare columns for context." 
+  },
+  {
+    "question": "List average payload tons per hauling company for the last 30 days.",
+    "sql": "SELECT TCompanyName, AVG(Tons) AS avg_tons, COUNT(*) AS load_count\nFROM dbo.SugarLoadData\nWHERE DateOut >= DATEADD(day, -30, SYSDATETIME())\n  AND Tons IS NOT NULL\nGROUP BY TCompanyName\nORDER BY avg_tons DESC;",
+    "notes": "Filters out null payloads and groups by company for business comparison." 
+  },
+  {
+    "question": "Which vehicles have missing tare weights on recent loads?",
+    "sql": "SELECT VehicleId_Fk, COUNT(*) AS missing_tare_count\nFROM dbo.SugarLoadData\nWHERE DateOut >= DATEADD(day, -14, SYSDATETIME())\n  AND (TareWt IS NULL OR TareWt = 0)\nGROUP BY VehicleId_Fk\nORDER BY missing_tare_count DESC;",
+    "notes": "Helps operations schedule tare recalibration." 
+  },
+  {
+    "question": "Provide hourly load counts for the current day.",
+    "sql": "SELECT DATEPART(hour, DateOut) AS hour_of_day, COUNT(*) AS loads\nFROM dbo.SugarLoadData\nWHERE DateOut >= CAST(SYSDATETIME() AS date)\nGROUP BY DATEPART(hour, DateOut)\nORDER BY hour_of_day;",
+    "notes": "Generates time-series data for real-time dashboards; assumes DateOut in local timezone." 
+  }
+]

ai_agents/db_agent/context/glossary.md

@@ -0,0 +1,44 @@
+# SugarScale MSSQL Glossary
+
+Use this glossary to translate operator language into database columns for the SQL agent.
+
+## Core Tables
+- **dbo.SugarLoadData**: Per-load grain deliveries recorded at the truck scale. Each row represents a truck entering/exiting the facility with weight measurements and logistics metadata.
+- **dbo.SugarVehicles**: Reference table for registered trucks/trailers and their default properties (company, RFID tag, tare weight).
+- **dbo.SugarParams**: System parameters; currently stores a single `StartTime` indicating when the scale captured data begins.
+
+## Common Terms
+- **Load** → `dbo.SugarLoadData`
+  - `SugarLoadID_Pk`: Unique identifier for a scale transaction (primary key).
+  - `VehicleId_Fk`: Truck or vehicle identifier referencing `dbo.SugarVehicles.VehicleId_Pk`.
+  - `TrailerTypeID`: Trailer classification (e.g., hopper, dump). Stored as free text; standardize before analytics when possible. 
+  - `TCompanyName`: Hauling company name as captured at the kiosk.
+  - `DriverID`: Driver badge or license; alphanumeric string up to 500 chars.
+  - `LoadingLocation`: Where the load originated (hopper, wh1, wh2, etc.).
+  - `Destination`: Planned delivery point or storage yard.
+  - `DateIn`: Timestamp when the vehicle weighed in (in local plant timezone).
+  - `DateOut`: Timestamp when the vehicle weighed out or exited.
+  - `ScaleWT`: Raw indicator from the scale prior to adjustments (integer pounds).
+  - `GrossWt`: Gross weight measured on exit, in pounds.
+  - `TareIN`: Tare weight observed on entry (empty truck), in pounds.
+  - `TareWt`: Tare weight applied for net calculations; may be sourced from default or reweigh.
+  - `Tons`: Net payload in short tons (calculated from gross-tare).
+  - `LoadType`: Category flag (e.g., sugar, molasses). Align with scheduling terminology.
+  - `Alt_Barcode_Scan`: Secondary barcode capture used for redundancy; 50-character limit.
+
+- **Vehicle** → `dbo.SugarVehicles`
+  - `VehicleId_Pk`: Unique truck identifier (matches `VehicleId_Fk`).
+  - `TCompanyName`: Default operator/contractor name for the vehicle record.
+  - `RFID`: RFID tag assigned to the truck for automatic gate reads.
+  - `Tare`: Stored tare weight (decimal, pounds). Use when `SugarLoadData.TareWt` is null.
+  - `LastTareTime`: Timestamp of the last verified tare measurement.
+  - `DefaultDest`: Common destination code used to prefill load forms.
+
+- **System Start** → `dbo.SugarParams.StartTime`
+  - Indicates the earliest reliable timestamp in the SugarLoadData feed; use when bounding historical reports.
+
+## Business Notes
+- Weight fields are stored in pounds except `Tons`, which is short tons (`lbs / 2000`). Convert before aggregating if downstream systems expect metric tons.
+- `DateIn` and `DateOut` are expected to be in local plant time without timezone metadata; adjust to UTC when integrating with other systems.
+- Null `VehicleId_Fk` rows usually indicate walk-on loads or manual overrides; treat carefully when joining to `SugarVehicles`.
+- `LoadType` and `TrailerTypeID` are free text and may have inconsistent casing; normalize to upper case when filtering.

ai_agents/db_agent/context/schema.json

@@ -0,0 +1,186 @@
+{
+  "tables": {
+    "dbo.SugarLoadData": {
+      "columns": [
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "SugarLoadID_Pk",
+          "nullable": false,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "VehicleId_Fk",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "TrailerTypeID",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "TCompanyName",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 500,
+          "name": "DriverID",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "LoadingLocation",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "Destination",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "DateIn",
+          "nullable": true,
+          "type": "datetime"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "DateOut",
+          "nullable": true,
+          "type": "datetime"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "ScaleWT",
+          "nullable": true,
+          "type": "int"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "GrossWt",
+          "nullable": true,
+          "type": "float"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "TareIN",
+          "nullable": true,
+          "type": "float"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "TareWt",
+          "nullable": true,
+          "type": "float"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "Tons",
+          "nullable": true,
+          "type": "float"
+        },
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "LoadType",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 50,
+          "name": "Alt_Barcode_Scan",
+          "nullable": true,
+          "type": "nvarchar"
+        }
+      ],
+      "name": "SugarLoadData",
+      "relationships": [],
+      "schema": "dbo"
+    },
+    "dbo.SugarParams": {
+      "columns": [
+        {
+          "default": null,
+          "max_length": null,
+          "name": "StartTime",
+          "nullable": false,
+          "type": "datetime"
+        }
+      ],
+      "name": "SugarParams",
+      "relationships": [],
+      "schema": "dbo"
+    },
+    "dbo.SugarVehicles": {
+      "columns": [
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "VehicleId_Pk",
+          "nullable": false,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 255,
+          "name": "TCompanyName",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": 150,
+          "name": "RFID",
+          "nullable": true,
+          "type": "nvarchar"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "Tare",
+          "nullable": true,
+          "type": "decimal"
+        },
+        {
+          "default": null,
+          "max_length": null,
+          "name": "LastTareTime",
+          "nullable": true,
+          "type": "datetime"
+        },
+        {
+          "default": null,
+          "max_length": 50,
+          "name": "DefaultDest",
+          "nullable": true,
+          "type": "nvarchar"
+        }
+      ],
+      "name": "SugarVehicles",
+      "relationships": [],
+      "schema": "dbo"
+    }
+  }
+}

ai_agents/db_agent/context/value_hints.yaml

@@ -0,0 +1,76 @@
+# Enum hints and typical ranges sourced from the SugarScale MSSQL sandbox.
+# Update these after running profiling queries to keep the agent grounded.
+
+columns:
+  dbo.SugarLoadData.LoadType:
+    values:
+      - Sugar
+      - Molases
+    notes: "Free-text field; normalize casing before comparisons."
+  dbo.SugarLoadData.TrailerTypeID:
+    values:
+      - Dump
+    notes: "Derived from manual entry; expect misspellings such as 'hopper' or 'Dump Trailer'."
+  dbo.SugarLoadData.LoadingLocation:
+    values:
+      - Hopper
+      - WH1
+      - WH2
+      - WH3
+      - BB
+    notes: "Locations map to historian area tags; keep a lookup table in sync with operations."
+  dbo.SugarLoadData.Destination:
+    values:
+      - Baldwin 3
+      - CSC
+      - BB
+      - Railcar
+      - LSR
+      - WH1
+      - WH2
+      - Barge
+      - Caldwell
+      - Other
+    notes: "Destination names align with production reporting dashboards; treat nulls as 'Unassigned'."
+  dbo.SugarLoadData.TCompanyName:
+    values:
+      - AOA
+      - JJAG,LLC
+      - Michael Durand
+      - Atchafalaya Seafood
+      - CSC
+      - Southern Prestige ENT
+      - LACA
+      - RALPH CALLIER
+      - ASR
+      - 14-1
+      - BIGDAWG
+      - Lasuca
+      - Earl Pania
+      - J Bradley
+    notes: "Company names align with production reporting dashboards; treat nulls as 'Unassigned'."
+
+ranges:
+  dbo.SugarLoadData.GrossWt:
+    units: pounds
+    typical_min: 20000
+    typical_max: 95000
+    notes: "Scale enforces 40-ton cap; values above 90000 suggest sensor error."
+  dbo.SugarLoadData.TareWt:
+    units: pounds
+    typical_min: 20000
+    typical_max: 45000
+    notes: "Use stored vehicle tare when this column is null; sudden drops >20% flag for review."
+  dbo.SugarLoadData.Tons:
+    units: short_tons
+    typical_min: 5
+    typical_max: 40
+    notes: "Calculated payload; negative values indicate data entry mistakes."
+
+confidence_flags:
+  dbo.SugarLoadData.VehicleId_Fk:
+    null_meaning: "Manual override or unregistered vehicle"
+    mitigation: "Join to SugarVehicles only after filtering nulls or alias to 'UNKNOWN_VEHICLE'."
+  dbo.SugarLoadData.DateOut:
+    null_meaning: "Truck has not exited; treat as active load."
+    mitigation: "Filter out null DateOut when reporting completed deliveries."