Skip to content

Add GSC opportunity scorer and wire into analytics/onboarding flows#436

Open
AJaySi wants to merge 1 commit intomainfrom
codex/create-opportunity-scorer-module-rrw4cv
Open

Add GSC opportunity scorer and wire into analytics/onboarding flows#436
AJaySi wants to merge 1 commit intomainfrom
codex/create-opportunity-scorer-module-rrw4cv

Conversation

@AJaySi
Copy link
Owner

@AJaySi AJaySi commented Mar 12, 2026

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant