feat(specs): add draft schema for Agentic Analytics

package.json

@@ -17,8 +17,10 @@
     "clean": "rm -rf **/dist **/build **/.build **/node_modules **/.gradle **/vendor **/bin **/obj **/__pycache__ || true",
     "cli": "yarn workspace scripts start",
     "docker:setup": "./scripts/docker/setup.sh",
+    "eslint": "eslint",
     "fix:json": "eslint '**/*.json' --fix",
     "github-actions:lint": "eslint '.github/**/*.yml'",
+    "lint-staged": "lint-staged",
     "postinstall": "husky && yarn workspace eslint-plugin-automation-custom build",
     "playground:browser": "yarn workspace javascript-browser-playground start",
     "scripts:build": "yarn workspace scripts build:actions",
@@ -48,5 +50,6 @@
   "engines": {
     "node": "^24.0.0",
     "yarn": "^4.0.0"
-  }
+  },
+  "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

specs/insights/common/schemas/AddedToCartObjectIDs.yml

@@ -27,6 +27,8 @@ properties:
     $ref: './EventAttributes.yml#/timestamp'
   value:
     $ref: './EventAttributes.yml#/value'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml

@@ -28,6 +28,8 @@ properties:
     $ref: './EventAttributes.yml#/timestamp'
   value:
     $ref: './EventAttributes.yml#/value'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ClickedFilters.yml

@@ -16,6 +16,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ClickedObjectIDs.yml

@@ -20,6 +20,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml

@@ -24,6 +24,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ConvertedFilters.yml

@@ -15,6 +15,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ConvertedObjectIDs.yml

@@ -20,6 +20,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml

@@ -24,6 +24,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/EventAttributes.yml

@@ -83,6 +83,37 @@ filters:
   maxItems: 20
   example: ['brand:apple']
 
+agent:
+  description: a set of fields for matching events to agent responses.
+  type: object
+  properties:
+    agentID:
+      description: the ID of the agent to which this event is related.
+      type: string
+      minLength: 1
+      maxLength: 256
+    messageID:
+      description: the ID of the agent message to which this event is related.
+      type: string
+      minLength: 1
+      maxLength: 256
+    toolCallID:
+      description: the ID of the instant-search tool to which this event is related.
+      type: string
+      minLength: 1
+      maxLength: 256
+    conversationID:
+      description: the ID of the instant-search conversation to which this event is related.
+      type: string
+      minLength: 1
+      maxLength: 256
+  required:
+    # Although all these fields are specified as optional in the Agentic Analytics document, now that they are grouped, it may
+    # make sense to make the parent property optional but require all sub properties to be supplied together, as here
+    - agentID
+    - messageID
+    - toolCallID
+    - conversationID
 positions:
   type: array
   items:
@@ -181,6 +212,17 @@ currency:
   description: Three-letter [currency code](https://www.iso.org/iso-4217-currency-codes.html).
   example: EUR
 
+sessionID:
+  type: string
+  # We don't necessarily need to be this restrictive:
+  pattern: '[0-9a-f]{32}'
+  minLength: 32
+  maxLength: 32
+  description: |
+    Unique identifier for a session
+    [TODO]: Document here where this is derived and how it is used.
+  example: 3e48cd0616e466948dd85abf5c3fbbe2
+
 value:
   description: |
     Total monetary value of this event in units of `currency`.

specs/insights/common/schemas/EventsItems.yml

@@ -11,3 +11,4 @@ oneOf:
   - $ref: './ConvertedFilters.yml'
   - $ref: './ViewedObjectIDs.yml'
   - $ref: './ViewedFilters.yml'
+  - $ref: './InstantSearchTelemetry.yml'

specs/insights/common/schemas/InstantSearchTelemetry.yml

@@ -0,0 +1,32 @@
+type: object
+title: Instant Search Telemetry Event
+description: |
+  Tracks an initial user interaction with the Agentic Analytics API.
+properties:
+  eventType:
+    $ref: './InstantSearchTelemetryEvent.yml'
+  eventName:
+    $ref: './EventAttributes.yml#/eventName'
+  sessionID:
+    $ref: './EventAttributes.yml#/sessionID'
+  userToken:
+    $ref: './EventAttributes.yml#/userToken'
+  # This is not specified in the Agentic Analytics document but is optional in all other schemas 
+  # Can we keep it here for consistency?
+  authenticatedUserToken:
+    $ref: './EventAttributes.yml#/authenticatedUserToken'
+  timestamp:
+    $ref: './EventAttributes.yml#/timestamp'
+  performance:
+    description: free form object for performance data.
+    type: object
+  widgets:
+    description: free form object for widget information.
+    type: object
+required:
+  - eventName
+  - sessionID
+  - eventType
+  - userToken
+x-discriminator-fields:
+  - eventType

specs/insights/common/schemas/InstantSearchTelemetryEvent.yml

@@ -0,0 +1,2 @@
+type: string
+enum: [instantsearch_telemetry]

specs/insights/common/schemas/PurchasedObjectIDs.yml

@@ -27,6 +27,8 @@ properties:
     $ref: './EventAttributes.yml#/timestamp'
   value:
     $ref: './EventAttributes.yml#/value'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml

@@ -26,6 +26,8 @@ properties:
     $ref: './EventAttributes.yml#/timestamp'
   value:
     $ref: './EventAttributes.yml#/value'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ViewedFilters.yml

@@ -19,6 +19,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/common/schemas/ViewedObjectIDs.yml

@@ -16,6 +16,8 @@ properties:
     $ref: './EventAttributes.yml#/authenticatedUserToken'
   timestamp:
     $ref: './EventAttributes.yml#/timestamp'
+  agent:
+    $ref: './EventAttributes.yml#/agent'
 required:
   - eventName
   - eventType

specs/insights/paths/pushEvents.yml

@@ -185,7 +185,22 @@ post:
                   userToken: anonymous-user-1
                   authenticatedUserToken: user-1
                   filters: ['category:books']
-
+          InstantSearchTelemetry:
+            summary: InstantSearch Telemetry event
+            value:
+              events:
+                - eventName: My Event Name
+                  eventType: instantsearch_telemetry
+                  index: test-index
+                  userToken: anonymous-user-1
+                  sessionID: f47ac10b-58cc-4372-a567-0e02b2c3d479
+                  client_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
+                  performance:
+                    foo: 343
+                    bar: 'blah'
+                  widgets:
+                    ping: 
+                      pong: 21
   responses:
     '200':
       description: OK
@@ -197,11 +212,7 @@ post:
             Success:
               summary: Events successfully sent to the Insights API
               description: >-
-                Success indicates that the Insights API received the events correctly,
-                and that event properties are formatted correctly.
-                Success doesn't imply that the event can be used by any Algolia feature.
-                For example, the Insights API doesn't check if the index name you provided exists,
-                or if the object IDs exist in your index.
+                Success indicates that the Insights API received the events correctly, and that event properties are formatted correctly. Success doesn't imply that the event can be used by any Algolia feature. For example, the Insights API doesn't check if the index name you provided exists, or if the object IDs exist in your index.
               value:
                 status: 200
                 message: OK
@@ -283,8 +294,7 @@ post:
             NoEvents:
               summary: No events
               description: >-
-                This can happen if you're sending an empty `events` array,
-                or if you try to send a single event object instead of the `events` array.
+                This can happen if you're sending an empty `events` array, or if you try to send a single event object instead of the `events` array.
               value:
                 status: 422
                 message: No events to process
@@ -360,8 +370,7 @@ post:
             WrongPositionsItems:
               summary: Wrong number of items in positions array
               description: >-
-                For click events with the `queryID` and `objectIDs` attributes,
-                you must include the `positions` attribute with the same number of items as the `objectIDs` attribute.
+                For click events with the `queryID` and `objectIDs` attributes, you must include the `positions` attribute with the same number of items as the `objectIDs` attribute.
               value:
                 status: 422
                 message: Event of type click should have the same number of ObjectIDs and Positions