Skip to content

Commit 832e523

Browse files
writeenswriteens
authored
docs(ai-perso): add ai-personalization spec file for documentation generation (#4063)
1 parent e50f0f6 commit 832e523

17 files changed

+646
-1
lines changed

‎scripts/common.ts

+7-1
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,13 @@ export const GENERATORS = Object.entries(clientsConfig).reduce(
6969

7070
export const LANGUAGES = [...new Set(Object.values(GENERATORS).map((gen) => gen.language))];
7171

72-
export const CLIENTS = [...new Set(Object.values(GENERATORS).map((gen) => gen.client)), 'crawler'];
72+
// `crawler` and `ai-personalization` are manually added so we can still bundled and validate the specs
73+
// the entry can be removed once at least one client is generated
74+
export const CLIENTS = [
75+
...new Set(Object.values(GENERATORS).map((gen) => gen.client)),
76+
'crawler',
77+
'ai-personalization',
78+
];
7379

7480
export async function run(command: string, { errorMessage, cwd, language }: RunOptions = {}): Promise<string> {
7581
const realCwd = path.resolve(ROOT_DIR, cwd ?? '.');

‎specs/ai-personalization/common/enums.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
errorCodes:
2+
title: errorCodes
3+
type: string
4+
enum:
5+
- blocked
6+
- deleted
7+
- no_perso_access
8+
- all_attr_value_filtered
9+
- missing_index
10+
- no_events_last_30_days
11+
- pending_pipelines
12+
- invalid_config
13+
14+
status:
15+
title: status
16+
type: string
17+
enum: [pending, active, paused]
18+
19+
sourceType:
20+
title: type
21+
type: string
22+
enum: [insights]

‎specs/ai-personalization/common/responses/BadRequest.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
description: Bad request.
2+
content:
3+
application/json:
4+
schema:
5+
$ref: './BaseResponse.yml'

‎specs/ai-personalization/common/responses/BaseResponse.yml

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
type: object
2+
properties:
3+
status:
4+
type: integer
5+
description: HTTP status code.
6+
message:
7+
type: string
8+
description: Details about the response, such as error messages.

‎specs/ai-personalization/common/responses/ConfigurationNotFound.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
description: Configuration not found.
2+
content:
3+
application/json:
4+
schema:
5+
$ref: './BaseResponse.yml'

‎specs/ai-personalization/common/responses/InternalServerError.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
description: Internal server error.
2+
content:
3+
application/json:
4+
schema:
5+
$ref: './BaseResponse.yml'

‎specs/ai-personalization/common/responses/InvalidUserID.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
description: Invalid user ID format.
2+
content:
3+
application/json:
4+
schema:
5+
$ref: './BaseResponse.yml'

‎specs/ai-personalization/common/responses/Unauthorized.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
description: Not authorized to access this resource.
2+
content:
3+
application/json:
4+
schema:
5+
$ref: './BaseResponse.yml'

‎specs/ai-personalization/common/responses/UserNotFound.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
description: User not found.
2+
content:
3+
application/json:
4+
schema:
5+
$ref: './BaseResponse.yml'

‎specs/ai-personalization/common/schemas/Configuration.yml

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
event:
2+
type: object
3+
properties:
4+
type:
5+
$ref: '#/eventType'
6+
subtype:
7+
$ref: '#/subtype'
8+
name:
9+
type: string
10+
required: [type, name]
11+
12+
events:
13+
type: object
14+
properties:
15+
viewDetails:
16+
type: array
17+
items:
18+
$ref: '#/event'
19+
viewListing:
20+
type: array
21+
items:
22+
$ref: '#/event'
23+
addToCart:
24+
type: array
25+
items:
26+
$ref: '#/event'
27+
purchase:
28+
type: array
29+
items:
30+
$ref: '#/event'
31+
required: [viewDetails, viewListing, addToCart, purchase]
32+
33+
issue:
34+
type: object
35+
description: An issue is either an 'error' or a 'warning' that is generated by the validator.
36+
properties:
37+
code:
38+
type: string
39+
index:
40+
type: string
41+
message:
42+
type: string
43+
required: [code, index, message]
44+
45+
personalizationReRanking:
46+
type: string
47+
description: The impact that personalization has on the re-ranking of search results.
48+
enum: [none, low, medium, high, maximum]
49+
50+
profileType:
51+
type: string
52+
enum: [basic, predictive]
53+
description: |
54+
The type of user profiles to generate.
55+
56+
Basic profiles are based on past behaviors, ensuring search results align with previous interests.
57+
Predictive profiles are AI-powered profiles that predict and adapt to users' interests, ensuring search results align with evolving preferences.
58+
59+
eventType:
60+
type: string
61+
enum: [view, click, conversion]
62+
63+
subtype:
64+
type: string
65+
enum: [addToCart, purchase]
66+
67+
status:
68+
type: object
69+
properties:
70+
type:
71+
$ref: '../enums.yml#/status'
72+
errors:
73+
type: array
74+
items:
75+
$ref: '../enums.yml#/errorCodes'

‎specs/ai-personalization/common/schemas/ConfigurationObject.yml

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
configurationObject:
2+
type: object
3+
properties:
4+
indices:
5+
type: array
6+
items:
7+
title: configurationObject
8+
type: object
9+
properties:
10+
index:
11+
type: string
12+
affinities:
13+
type: array
14+
items:
15+
type: string
16+
source:
17+
title: source
18+
type: object
19+
properties:
20+
type:
21+
$ref: '../enums.yml#/sourceType'
22+
events:
23+
$ref: './Configuration.yml#/events'
24+
errors:
25+
type: array
26+
items:
27+
$ref: './Configuration.yml#/issue'
28+
warnings:
29+
type: array
30+
items:
31+
$ref: './Configuration.yml#/issue'
32+
lastUpdatedAt:
33+
type: string
34+
required: [index, affinities, source, errors, warnings, lastUpdatedAt]
35+
personalizationReRanking:
36+
$ref: './Configuration.yml#/personalizationReRanking'
37+
profileType:
38+
$ref: './Configuration.yml#/profileType'
39+
status:
40+
$ref: './Configuration.yml#/status'
41+
required: [indices, personalzationReRanking, profileType, status]

‎specs/ai-personalization/common/schemas/User.yml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
user:
2+
type: object
3+
properties:
4+
userID:
5+
type: string
6+
affinities:
7+
type: array
8+
items:
9+
title: affinity
10+
type: object
11+
properties:
12+
name:
13+
type: string
14+
indices:
15+
type: array
16+
items:
17+
type: string
18+
minimum: 1
19+
value:
20+
type: string
21+
score:
22+
type: number
23+
minimum: 1
24+
maximum: 20
25+
lastUpdatedAt:
26+
type: string
27+
required: [name, indices, value, score, lastUpdatedAt]
28+
lastUpdatedAt:
29+
type: string
30+
required: [userID, affinities, lastUpdatedAt]

‎specs/ai-personalization/common/schemas/UsersParams.yml

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# query
2+
startDate:
3+
name: startDate
4+
description: |
5+
Filter users by start date (in RFC3339 format).
6+
Only users that were updated after the passed date will be returned.
7+
in: query
8+
schema:
9+
type: string
10+
example: 2024-06-27T08:27:26Z
11+
12+
endDate:
13+
name: endDate
14+
description: |
15+
Filter users by end date (in RFC3339 format).
16+
Only users that were updated before the passed date will be returned.
17+
in: query
18+
schema:
19+
type: string
20+
example: 2024-06-28T08:27:26Z
21+
22+
indices:
23+
name: indices
24+
description: |
25+
Filter users by matching indices.
26+
If multiple indices are passed, returned users will match all indices.
27+
in: query
28+
schema:
29+
type: array
30+
items:
31+
type: string
32+
examples:
33+
singleIndex:
34+
value: [products_EN]
35+
summary: Filter by single index
36+
multipleIndices:
37+
value: [products_EN, products_FR]
38+
summary: Filter by multiple indices
39+
style: form
40+
explode: false
41+
42+
affinity:
43+
name: affinity
44+
description: |
45+
Filter users by affinity name and value.
46+
If multiple values are passed, returned users will match all values.
47+
in: query
48+
schema:
49+
type: array
50+
items:
51+
type: string
52+
examples:
53+
affinityName:
54+
value: brand
55+
summary: Filter by single affinity name
56+
affinityValuePair:
57+
value: brand:Nike
58+
summary: Filter by single affinity name and value
59+
multipleAffinityNames:
60+
value: brand,color
61+
summary: Filter by multiple affinity names
62+
multipleAffinityValuePairs:
63+
value: brand:Nike,color:white
64+
summary: Filter by multiple affinity name and value pairs
65+
66+
limit:
67+
name: limit
68+
description: |
69+
Limit the number of users in the response.
70+
The value of this parameter ranges from 1 to 1000.
71+
in: query
72+
schema:
73+
type: integer
74+
default: 10
75+
minimum: 1
76+
maximum: 1000
77+
78+
nextPageToken:
79+
name: nextPageToken
80+
description: |
81+
Reference for the next page, when navigating forward using pagination.
82+
Can't be used in the same request as `previousPageToken`.
83+
in: query
84+
schema:
85+
type: string
86+
87+
previousPageToken:
88+
name: previousPageToken
89+
description: |
90+
Reference for the previous page, when navigating backward using pagination.
91+
Can't be used in the same request as `nextPageToken`.
92+
in: query
93+
schema:
94+
type: string
95+
96+
# path
97+
98+
userID:
99+
name: userID
100+
description: ID of the user.
101+
in: path
102+
required: true
103+
schema:
104+
type: string

0 commit comments

Comments
 (0)