Improve section ranking for overlapping overview and API excerpts

[ayhammouda]

Closes #134

Overlapping overview excerpts could fill the result budget before a later, narrower API anchor was considered. Ranking now examines a bounded candidate window and prefers the canonical API section when the content and matched excerpts are substantially redundant. Distinct topics, direct anchors and whole-page retrieval remain available.

Validation on exact head 68020734df935e6b99efb0096bf9996702b9282e:

• Independent isolated review approved with no blockers; locked dependency sync, Ruff, Pyright and pytest passed (542 passed, one platform-specific skip).
• A freshly built Python 3.11–3.13 index contained 1,603 documents. All 65 frozen retrieval/citation cases passed with no regressions. Base and head each had 8 retrieval hits and 69 resolved citations; representative real-index queries removed overlapping itertools overview hits. No frozen-corpus gain or generated-answer accuracy improvement is claimed.
• All eleven required hosted checks passed, including installed-package smoke, product regression, dependency audit and CodeQL.

Exact-head independent verification is recorded by the guarded broker. No dependency, workflow, corpus, baseline, MCP schema or governance change is included; no paid benchmark calls were made.

[coderabbiteu]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: ayhammouda/python-docs-mcp-server/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: f71cf528-4cfc-470c-823c-3b52b395ed71

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 32 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: ayhammouda/python-docs-mcp-server/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: c90a48f5-c56b-4489-bde1-96715a3e2751

📥 Commits

Reviewing files that changed from the base of the PR and between e2e22ba and 6802073.

⛔ Files ignored due to path filters (1)

• docs/architecture/DESIGN.md is excluded by none and included by none

📒 Files selected for processing (2)

• src/mcp_server_python_docs/retrieval/ranker.py
• tests/test_retrieval.py

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ayhammouda]

Vision — automated project maintainer

Independent verification (temporary credential): success

Head: 68020734df935e6b99efb0096bf9996702b9282e; main: e2e22ba6e947d5ac2e82f7bab5688a29c62f495d.

{
  "head_sha": "68020734df935e6b99efb0096bf9996702b9282e",
  "base_sha": "e2e22ba6e947d5ac2e82f7bab5688a29c62f495d",
  "approved": true,
  "summary": "Independent review of the exact diff found a scoped, read-only section-ranking change with deterministic overlap tests and no dependency, workflow, corpus, baseline, or governance changes. The full three-version index contained 1,603 documents; the offline gate passed all 65 cases. Base and head each had 8 retrieval hits and 69 resolved citations, with no case-level change. Representative real-index queries showed redundant itertools overview hits removed, but no frozen-corpus improvement. Hosted CI is pending because this head is unpublished.",
  "commands": [
    {
      "command": "git clone --depth=1 https://github.com/ayhammouda/python-docs-mcp-server.git repo",
      "exit_code": 0
    },
    {
      "command": "git fetch --depth=1 origin 68020734df935e6b99efb0096bf9996702b9282e e2e22ba6e947d5ac2e82f7bab5688a29c62f495d",
      "exit_code": 0
    },
    {
      "command": "git diff --find-renames e2e22ba6e947d5ac2e82f7bab5688a29c62f495d 68020734df935e6b99efb0096bf9996702b9282e",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv sync --locked --dev",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked ruff check src/ tests/ benchmarks/ ops/ .github/scripts/",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked pyright src/ benchmarks/",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked pytest --tb=short -q",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked pytest -q tests/test_retrieval.py",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python -m benchmarks validate-corpus --corpus docs/benchmarks/corpus.yml --schema docs/benchmarks/corpus.schema.json",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python-docs-mcp-server build-index --versions 3.11,3.12,3.13",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python-docs-mcp-server doctor",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python -m benchmarks.regression --index /tmp/cache/mcp-python-docs/index.db --output /tmp/pd-head-regression.json",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python -m benchmarks.regression --index /tmp/cache/mcp-python-docs/index.db --output /tmp/pd-base-regression.json",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python /tmp/pd_compare_queries.py",
      "exit_code": 0
    },
    {
      "command": "git diff --check e2e22ba6e947d5ac2e82f7bab5688a29c62f495d 68020734df935e6b99efb0096bf9996702b9282e",
      "exit_code": 0
    },
    {
      "command": "git ls-remote origin refs/heads/main refs/pull/134/head",
      "exit_code": 0
    }
  ],
  "blockers": []
}

[ayhammouda]

Vision — automated project maintainer

Independent verification (temporary credential): success

Head: 68020734df935e6b99efb0096bf9996702b9282e; main: e2e22ba6e947d5ac2e82f7bab5688a29c62f495d.

{
  "head_sha": "68020734df935e6b99efb0096bf9996702b9282e",
  "base_sha": "e2e22ba6e947d5ac2e82f7bab5688a29c62f495d",
  "approved": true,
  "summary": "Independent review of the exact diff found a scoped, read-only section-ranking change with deterministic overlap tests and no dependency, workflow, corpus, baseline, or governance changes. The full three-version index contained 1,603 documents; the offline gate passed all 65 cases. Base and head each had 8 retrieval hits and 69 resolved citations, with no case-level change. Representative real-index queries showed redundant itertools overview hits removed, but no frozen-corpus improvement. Hosted CI is pending because this head is unpublished.",
  "commands": [
    {
      "command": "git clone --depth=1 https://github.com/ayhammouda/python-docs-mcp-server.git repo",
      "exit_code": 0
    },
    {
      "command": "git fetch --depth=1 origin 68020734df935e6b99efb0096bf9996702b9282e e2e22ba6e947d5ac2e82f7bab5688a29c62f495d",
      "exit_code": 0
    },
    {
      "command": "git diff --find-renames e2e22ba6e947d5ac2e82f7bab5688a29c62f495d 68020734df935e6b99efb0096bf9996702b9282e",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv sync --locked --dev",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked ruff check src/ tests/ benchmarks/ ops/ .github/scripts/",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked pyright src/ benchmarks/",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked pytest --tb=short -q",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked pytest -q tests/test_retrieval.py",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python -m benchmarks validate-corpus --corpus docs/benchmarks/corpus.yml --schema docs/benchmarks/corpus.schema.json",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python-docs-mcp-server build-index --versions 3.11,3.12,3.13",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python-docs-mcp-server doctor",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python -m benchmarks.regression --index /tmp/cache/mcp-python-docs/index.db --output /tmp/pd-head-regression.json",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python -m benchmarks.regression --index /tmp/cache/mcp-python-docs/index.db --output /tmp/pd-base-regression.json",
      "exit_code": 0
    },
    {
      "command": "/usr/local/bin/uv run --locked python /tmp/pd_compare_queries.py",
      "exit_code": 0
    },
    {
      "command": "git diff --check e2e22ba6e947d5ac2e82f7bab5688a29c62f495d 68020734df935e6b99efb0096bf9996702b9282e",
      "exit_code": 0
    },
    {
      "command": "git ls-remote origin refs/heads/main refs/pull/134/head",
      "exit_code": 0
    }
  ],
  "blockers": []
}

[ayhammouda]

Vision — automated project maintainer: merge decision for #134.

The PR head is 68020734df935e6b99efb0096bf9996702b9282e against main e2e22ba6e947d5ac2e82f7bab5688a29c62f495d. Independent exact-head verification succeeded with no blockers: #137 (comment). The verifier rebuilt the 1,603-document Python 3.11–3.13 index, passed the locked lint/type/test/doctor/corpus checks and the frozen 65-case offline gate. Base and head each had 8 retrieval hits and 69 resolved citations; this is no regression, not a measured frozen-corpus gain or answer-accuracy claim. The deterministic limited-slot tests and representative real-index queries support the narrower user-problem fix.

All 11 exact-head GitHub checks are successful, including the six Python matrix jobs, installed-package smoke, product regression, dependency audit and CodeQL/Analyze. The Security Audit workflow succeeded. No submitted reviews or inline findings are open. CodeRabbit skipped due repository star threshold/free review limit; it did not provide independent approval. Scope is retrieval ranking, tests and design documentation only; no public MCP API, schema, ingestion, dependency, workflow, license or test weakening.

I will use the broker's SHA-matched merge gate; no protection bypass. Outcome review remains due 2026-10-16, and this behavior should be revisited if real feedback shows useful overview context is hidden or the frozen gate loses hits/citations. Releases remain deferred while release authorization is disabled.