[PR #436] Add GSC opportunity scorer and wire into analytics/onboarding flows #739

New issue

Open

opened 2026-03-13 21:06:36 +03:00 by kerem · 0 comments

kerem commented

2026-03-13 21:06:36 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/AJaySi/ALwrity/pull/436
Author: @AJaySi
Created: 3/12/2026
Status: 🔄 Open

Base: main ← Head: codex/create-opportunity-scorer-module-rrw4cv

📝 Commits (1)

20145f7 Add analytics opportunity scorer and integrate into GSC flows

📊 Changes

4 files changed (+348 additions, -1 deletions)

View changed files

📝 backend/api/content_planning/services/content_strategy/onboarding/data_integration.py (+74 -0)
📝 backend/services/analytics/handlers/gsc_handler.py (+87 -1)
➕ backend/services/analytics/opportunity_scorer.py (+128 -0)
📝 backend/services/gsc_service.py (+59 -0)

📄 Description

Motivation

Provide a reusable opportunity-scoring module that identifies high-impact search opportunities from normalized GSC rows so UI/agents can consume a single stable schema.
Enable window-over-window comparisons by returning a previous_period payload from the GSC service so rising/declining trends can be detected.
Integrate scoring into both the realtime analytics handler and the onboarding data flow so both surface the same ranked opportunities.
Skills: no AGENTS skill was needed for this change (helpers and integrations implemented directly).

Description

Added backend/services/analytics/opportunity_scorer.py with pure functions: high_impression_low_ctr_queries, rising_queries, declining_pages, score_and_rank_opportunities, and categorize_opportunities, returning the stable opportunity schema (id, query, page_url, reason, score, current_metrics, previous_metrics).
Integrated scorer in GSCAnalyticsHandler by normalizing current/previous query & page rows, calling categorize_opportunities(...), and returning opportunities alongside existing metrics in handler responses.
Extended GSCService.get_search_analytics to compute a matching previous-date window and optionally fetch previous-period query and page rows (added previous_period in the analytics payload) to enable window-over-window deltas.
Hooked opportunity extraction into onboarding integration (backend/api/content_planning/.../data_integration.py) so _get_gsc_analytics includes opportunities in its output and the onboarding flow reuses the same stable schema.

Testing

Compiled modified modules with python -m py_compile backend/services/analytics/opportunity_scorer.py backend/services/analytics/handlers/gsc_handler.py backend/services/gsc_service.py backend/api/content_planning/services/content_strategy/onboarding/data_integration.py; compilation succeeded.
Ran a focused smoke test invoking the scorer (from services.analytics.opportunity_scorer import categorize_opportunities) with representative query/page rows to validate categorization and ranking; the function produced a ranked list matching the stable schema.

Codex Task

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/AJaySi/ALwrity/pull/436 **Author:** [@AJaySi](https://github.com/AJaySi) **Created:** 3/12/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/create-opportunity-scorer-module-rrw4cv` --- ### 📝 Commits (1) - [`20145f7`](https://github.com/AJaySi/ALwrity/commit/20145f7ea4a84d05b54fedd391faa7f17c3f984d) Add analytics opportunity scorer and integrate into GSC flows ### 📊 Changes **4 files changed** (+348 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `backend/api/content_planning/services/content_strategy/onboarding/data_integration.py` (+74 -0) 📝 `backend/services/analytics/handlers/gsc_handler.py` (+87 -1) ➕ `backend/services/analytics/opportunity_scorer.py` (+128 -0) 📝 `backend/services/gsc_service.py` (+59 -0) </details> ### 📄 Description ### Motivation - Provide a reusable opportunity-scoring module that identifies high-impact search opportunities from normalized GSC rows so UI/agents can consume a single stable schema. - Enable window-over-window comparisons by returning a `previous_period` payload from the GSC service so rising/declining trends can be detected. - Integrate scoring into both the realtime analytics handler and the onboarding data flow so both surface the same ranked opportunities. - Skills: no AGENTS skill was needed for this change (helpers and integrations implemented directly). ### Description - Added `backend/services/analytics/opportunity_scorer.py` with pure functions: `high_impression_low_ctr_queries`, `rising_queries`, `declining_pages`, `score_and_rank_opportunities`, and `categorize_opportunities`, returning the stable opportunity schema (`id`, `query`, `page_url`, `reason`, `score`, `current_metrics`, `previous_metrics`). - Integrated scorer in `GSCAnalyticsHandler` by normalizing current/previous query & page rows, calling `categorize_opportunities(...)`, and returning `opportunities` alongside existing metrics in handler responses. - Extended `GSCService.get_search_analytics` to compute a matching previous-date window and optionally fetch previous-period `query` and `page` rows (added `previous_period` in the analytics payload) to enable window-over-window deltas. - Hooked opportunity extraction into onboarding integration (`backend/api/content_planning/.../data_integration.py`) so `_get_gsc_analytics` includes `opportunities` in its output and the onboarding flow reuses the same stable schema. ### Testing - Compiled modified modules with `python -m py_compile backend/services/analytics/opportunity_scorer.py backend/services/analytics/handlers/gsc_handler.py backend/services/gsc_service.py backend/api/content_planning/services/content_strategy/onboarding/data_integration.py`; compilation succeeded. - Ran a focused smoke test invoking the scorer (`from services.analytics.opportunity_scorer import categorize_opportunities`) with representative query/page rows to validate categorization and ranking; the function produced a ranked list matching the stable schema. ------ [Codex Task](https://chatgpt.com/codex/tasks/task_e_69b26cb7a7948328a65fdff63c487bb9) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem added the

pull-request

label

2026-03-13 21:06:36 +03:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/ALwrity#739

No description provided.

Rows
Columns