Skip to content

feat(keywords): add estimated difficulty core#36

Draft
hubab1 wants to merge 2 commits into
19b-ranking-provider-wiringfrom
20a-estimated-difficulty-core
Draft

feat(keywords): add estimated difficulty core#36
hubab1 wants to merge 2 commits into
19b-ranking-provider-wiringfrom
20a-estimated-difficulty-core

Conversation

@hubab1

@hubab1 hubab1 commented Jul 19, 2026

Copy link
Copy Markdown
Owner

Summary

  • add a deterministic, versioned estimated keyword-difficulty heuristic over the top 10 ranking results
  • return structured per-result evidence, confidence, unavailable reasons, algorithm identity, and explanatory notes
  • preserve exact selected-result title/subtitle evidence and retain distinct apps when provider positions collide
  • keep the core behavior-inert: no persistence, UI, MCP surface, network request, provider provenance, or Apple Ads metric state is changed here

Scoring model

  • authority: position-weighted log10(ratingCount + 1) / 6, capped at one million ratings
  • metadata saturation: keyword-token coverage in title and subtitle, with exact phrase matching retained as evidence only
  • final score: 70% authority and 30% metadata saturation, rounded and clamped to 0...100
  • confidence: geometric combination of top-10 sample coverage and rating-evidence coverage

The implementation explicitly identifies this as an OpenASO estimate, not Apple Ads difficulty, Search Popularity, or an Apple-provided metric.

Scope and follow-ups

This is the pure computation core for roadmap item 20a. Persistence and provenance belong in 20b; user-facing and MCP integration belong in 20c. This PR is stacked on #35 and remains draft while that manual provider-wiring gate is reviewed.

Attribution

The feature direction was informed by this upstream WIP commit: akshaynexus@5de98ea

The formula, evidence model, missing-data behavior, normalization, and tests were independently specified and rewritten for this repository. No co-author trailer is used.

Validation

  • 20 focused estimator tests pass
  • 283/283 complete tests pass
  • signed Debug build and strict code-sign verification succeed
  • exact built app remains running through a 3-second launch smoke test
  • independent amendment review reports no P1/P2 findings
  • prior architecture, formula, and attribution reviews report no P1/P2 findings

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant