We will likely already use search API to grab and iterate over a list of <unillustrated articles that have suggestions> in the other maintenance script to generate notifications (T292147)
I think we can use the same method of gathering the pages, except that we'd also use deepcat (limited to 5 levels deep and 256 categories in total) to find pages within certain categories.
@dcausse would using deepcat for a manually run script (probably only a few times) to fully iterate over all pages within a certain category be problematic for Search?

@matthiasmullie I don't think this would be problematic but it will be limited to the ability of blazegraph to return the full category hierarchy and by the way deepcat is currently constructing its elasticsearch query.

If you hit blazegraph timeouts we can get increased timeouts by running the query on the blazegraph machines.
The elasticsearch query issued by deepcat is a boolean and thus limited to 1024 clauses (hard limit) but it could be constructed with a terms query that can accept up to 64k terms.

For reference the SPARQL query used is:

SELECT ?out WHERE {
      SERVICE mediawiki:categoryTree {
          bd:serviceParam mediawiki:start <https://commons.wikimedia.org/wiki/Category:Nature> .
          bd:serviceParam mediawiki:direction "Reverse" .
          bd:serviceParam mediawiki:depth 5 .
      }
} ORDER BY ASC(?depth)
LIMIT 256

which you can query using curl --data-urlencode query@query.sparql -d format=json https://query.wikidata.org/bigdata/namespace/categories/sparql | jq -r ".results.bindings[] | .out.value".
You can try varying depth and limit to see if you can extract the full set.

Please let me know if you need help on this.

Questions:

• Will we send a notification for every unillustrated article within the categor(y|ies), or is there a maximum per user?
• In the case of multiple users, should every user receive the notifications, or should every notification be unique? (given 3 users & 6 articles, should all 3 users get 6 notifications, or should they all receive 2?)

Until I hear back, I'm going to assume that:

• There will be a maximum number of notifications per user per run of the script
• We are sending notifications for all pages, distributed evenly across users (until said maximum is reached for everyone)
• Same for next runs, except that users will no longer receive notifications about:
  • Pages that have since already been illustrated
  • Pages that they have already received a notification for

In T306272#8065144, @matthiasmullie wrote:

Questions:

• Will we send a notification for every unillustrated article within the categor(y|ies), or is there a maximum per user?
• In the case of multiple users, should every user receive the notifications, or should every notification be unique? (given 3 users & 6 articles, should all 3 users get 6 notifications, or should they all receive 2?)

Until I hear back, I'm going to assume that:

• There will be a maximum number of notifications per user per run of the script
• We are sending notifications for all pages, distributed evenly across users (until said maximum is reached for everyone)
• Same for next runs, except that users will no longer receive notifications about:
  • Pages that have since already been illustrated
  • Pages that they have already received a notification for

Thanks for asking these questions! Your assumptions are correct.

Is it possible to do a maximum number of notifications per user per run of the script (let's say a default of 10), but make that easily configurable per run of the script? So that the event coordinators can let us know ahead of time, when they provide the list of users, how many notifications each user should receive for this event?

• We are sending notifications for all pages, distributed evenly across users (until said maximum is reached for everyone)

Yes, every notification should be unique per run of the script.

In T306272#8065169, @CBogen wrote:

Is it possible to do a maximum number of notifications per user per run of the script (let's say a default of 10), but make that easily configurable per run of the script? So that the event coordinators can let us know ahead of time, when they provide the list of users, how many notifications each user should receive for this event?

Yes, it will be possible to narrow down the amount of notifications sent per user per run (as well as the possibility to exclude biographies (T295369) and suggestions below a certain confidence score)

Change 812324 had a related patch set uploaded (by Matthias Mullie; author: Matthias Mullie):

[mediawiki/extensions/ImageSuggestions@master] Add script to generate notifications for a given list of users & categories

https://gerrit.wikimedia.org/r/812324

@matthiasmullie I updated this ticket to add another AC based on discussions with WMPT who will be using this for an event in October:

The script can be configured to run more frequently and send more notifications than the existing scripts; e.g. for a particular event timespan, a script can be run daily instead of weekly and send 5 notifications per run instead of 2

Please let me know if there are any issues with this, thanks!

@matthiasmullie for clarity, I also just added this AC:

The script is not limited by the same constraints as the existing script (T292147), e.g. users do not need to have 500 edits

The script can be configured to run more frequently and send more notifications than the existing scripts; e.g. for a particular event timespan, a script can be run daily instead of weekly and send 5 notifications per run instead of 2

Since this will have no fixed parameters and configuration is likely to change often, this can not be a scheduled script.
We can run this whenever we want (assuming someone's around to run it)

Available parameters from script:

• user (accepts any list of user names - watchlist & number of edits don't matter, only their opt-in status for these notifications does)
• category (accepts any list of category titles - notifications will be sent for pages in these categories and their deepcat (limited to 5 levels deep and 256 categories in total) results)
• min-confidence (like with our other script, allows setting a suggestion confidence threshold)
• max-notifications-per-user (like with our other script, allows defining a max number of notifications per user per run)
• exclude-instance-of (like with our other script, can be used to omit certain types of pages, e.g. biographies)

The script's rules and availability are documented

What kind of details should be documented & where?

An SLA exists for the turnaround time needed if a user or campaign manager is requesting that the script be run

Who will work on this? ^
If we have an idea of expectations from campaigns, please LMK and I can check whether we're able to accommodate.
Limitations on our end are essentially our (flexible) working hours, and potentially unpredictable events (outages, breaks in code we rely on, ...)

In T306272#8224524, @matthiasmullie wrote:

The script can be configured to run more frequently and send more notifications than the existing scripts; e.g. for a particular event timespan, a script can be run daily instead of weekly and send 5 notifications per run instead of 2

Since this will have no fixed parameters and configuration is likely to change often, this can not be a scheduled script.
We can run this whenever we want (assuming someone's around to run it)

Got it, makes sense.

Available parameters from script:

• user (accepts any list of user names - watchlist & number of edits don't matter, only their opt-in status for these notifications does)
• category (accepts any list of category titles - notifications will be sent for pages in these categories and their deepcat (limited to 5 levels deep and 256 categories in total) results)
• min-confidence (like with our other script, allows setting a suggestion confidence threshold)
• max-notifications-per-user (like with our other script, allows defining a max number of notifications per user per run)
• exclude-instance-of (like with our other script, can be used to omit certain types of pages, e.g. biographies)

The script's rules and availability are documented

What kind of details should be documented & where?

Pretty much exactly what you documented above! Can we put it here? If you can fill in those details, as well as the SLA info (more on that below), I can add the info on how to request the script be run and why it exists. https://www.mediawiki.org/wiki/Structured_Data_Across_Wikimedia/Image_Suggestions/Category_Based_Notifications

An SLA exists for the turnaround time needed if a user or campaign manager is requesting that the script be run

Who will work on this? ^
If we have an idea of expectations from campaigns, please LMK and I can check whether we're able to accommodate.
Limitations on our end are essentially our (flexible) working hours, and potentially unpredictable events (outages, breaks in code we rely on, ...)

I was hoping you could tell me what we can accommodate. If we say the request with all details must be in a week before the event, is that sufficient to make sure we'll have someone around who can run it, and accommodate working hours and unpredictable events? Is two weeks better? A month? Thanks!

In T306272#8236909, @CBogen wrote:

I was hoping you could tell me what we can accommodate. If we say the request with all details must be in a week before the event, is that sufficient to make sure we'll have someone around who can run it, and accommodate working hours and unpredictable events? Is two weeks better? A month? Thanks!

Timing for the script may be more problematic - we don't have good geographic coverage, and even if we did, events could be happening (e.g. deployments, backports, outages, other requests, ...) that may prevent us from running a script at a specific time. And even then, script duration will vary quite a lot based on # users & categories.
We can't promise things like "run the script at Wednesday 3PM".
Best granularity is probably 24h: "the script can be run within 24h (on weekdays) prior to the requested time".

Finding someone who can run the script likely isn't going to be a problem. 1 week notice should be plenty.
(Note: that is for as long as we're actively working on this extension; once we move on, things could begin to break without us noticing in time, and 1 week may not be enough to fix)

Shorter turnarounds should certainly be possible & I wouldn't mind anyone trying to get a late request in, but we simply can't commit to being able to serve such requests under all circumstances.

How much of these requests do we expect?

In T306272#8263915, @matthiasmullie wrote:

In T306272#8236909, @CBogen wrote:

I was hoping you could tell me what we can accommodate. If we say the request with all details must be in a week before the event, is that sufficient to make sure we'll have someone around who can run it, and accommodate working hours and unpredictable events? Is two weeks better? A month? Thanks!

Timing for the script may be more problematic - we don't have good geographic coverage, and even if we did, events could be happening (e.g. deployments, backports, outages, other requests, ...) that may prevent us from running a script at a specific time. And even then, script duration will vary quite a lot based on # users & categories.
We can't promise things like "run the script at Wednesday 3PM".
Best granularity is probably 24h: "the script can be run within 24h (on weekdays) prior to the requested time".

Finding someone who can run the script likely isn't going to be a problem. 1 week notice should be plenty.
(Note: that is for as long as we're actively working on this extension; once we move on, things could begin to break without us noticing in time, and 1 week may not be enough to fix)

Shorter turnarounds should certainly be possible & I wouldn't mind anyone trying to get a late request in, but we simply can't commit to being able to serve such requests under all circumstances.

How much of these requests do we expect?

This all sounds reasonable to me! I think our SLO should be one month to account for things breaking when we're not actively working on the extension. We can note that we can try to meet shorter timelines, we just can't guarantee it.

I don't expect these requests to be very frequent; only for certain events maybe a few times a year at most.

Change 812324 merged by jenkins-bot:

[mediawiki/extensions/ImageSuggestions@master] Add script to generate notifications for a given list of users & categories

https://gerrit.wikimedia.org/r/812324

@matthiasmullie now that we've done a successful test run as part of T327209: [S] Send image suggestions notifications for Feb 11 WMPT event, and the first real use of that script will happen in that task, I believe the only remaining AC for this task is the documentation and SLA. I made an attempt at https://www.mediawiki.org/wiki/Structured_Data_Across_Wikimedia/Image_Suggestions/Category_Based_Notifications - could you take a look and close this ticket if you're happy with it?