oeis-seek 0.1.0__tar.gz

oeis_seek-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+# Least privilege: lint and tests only read the checkout; they publish nothing.
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1
+      - name: Sync dependencies
+        run: uv sync --frozen
+      - name: Lint
+        run: uv run ruff check .
+      - name: Test
+        run: uv run pytest

oeis_seek-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+# Publish to PyPI when a version tag (v*) is pushed. Trusted Publishing (OIDC)
+# mints a short-lived token at run time, so no API token is ever stored in the
+# repository or its secrets. The PyPI trusted publisher must be registered first
+# (project: oeis-seek, workflow: release.yml, environment: pypi). Tests run before
+# the build because a published version is immutable and cannot be replaced.
+#
+# pypa/gh-action-pypi-publish is a drop-in alternative if uv-native publishing is
+# ever unavailable.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+# Least privilege: the workflow needs nothing from the repository token. The OIDC
+# id-token is granted only to the release job, the sole job that publishes.
+permissions: {}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/oeis-seek
+    permissions:
+      id-token: write # mint the OIDC token Trusted Publishing exchanges with PyPI
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1
+      - name: Sync dependencies
+        run: uv sync --frozen
+      - name: Test
+        run: uv run pytest
+      - name: Build the sdist and wheel
+        run: uv build
+      - name: Publish to PyPI via Trusted Publishing
+        run: uv publish --trusted-publishing always

oeis_seek-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Project-management workspace is tracked separately, not in app source control.
+.project-management/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+
+# Build artifacts
+dist/
+build/

oeis_seek-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 niarenaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oeis_seek-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: oeis-seek
+Version: 0.1.0
+Summary: Transform-aware identifier for OEIS integer sequences
+Project-URL: Homepage, https://github.com/niarenaw/oeis-seek
+Project-URL: Repository, https://github.com/niarenaw/oeis-seek
+Project-URL: Issues, https://github.com/niarenaw/oeis-seek/issues
+Author: niarenaw
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,integer-sequences,mathematics,oeis,sequence
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.0
+Description-Content-Type: text/markdown
+
+# oeis-seek
+
+[![CI](https://github.com/niarenaw/oeis-seek/actions/workflows/ci.yml/badge.svg)](https://github.com/niarenaw/oeis-seek/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/oeis-seek.svg)](https://pypi.org/project/oeis-seek/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Identify the OEIS sequence a list of integers belongs to - even when the raw
+numbers are not in OEIS but a simple transform of them is.
+
+`oeis-seek` works offline against a local copy of the
+[OEIS](https://oeis.org/) bulk dump. You download the dump once, then look up
+sequences with no network calls and no rate limits.
+
+## Install
+
+Install the released CLI from PyPI (the package is `oeis-seek`; it installs a
+`oeis-seek` command):
+
+```bash
+uv tool install oeis-seek    # or: pipx install oeis-seek, or: pip install oeis-seek
+```
+
+Or work from a clone:
+
+```bash
+uv sync
+```
+
+## Usage
+
+First, download and index the OEIS dump (one time; re-run to refresh):
+
+```bash
+oeis-seek update
+```
+
+Then identify a sequence:
+
+```bash
+oeis-seek 0,1,1,2,3,5,8,13          # -> A000045 (Fibonacci), raw match
+oeis-seek 2,6,12,20,30,42           # -> hit via first differences
+echo "1 2 6 24 120" | oeis-seek     # terms from stdin
+oeis-seek 2,6,12,20 --json          # machine-readable output
+oeis-seek 2,6,12,20 --limit 5       # cap results (default 10)
+```
+
+Terms may be comma- or whitespace-separated, passed as arguments or piped on
+stdin. At least four terms are required by default (`--min-terms` lowers it).
+
+## How it works
+
+Three ideas do the work.
+
+### The matcher (framed-substring contiguous match)
+
+The index stores each sequence's terms as a comma-framed string,
+`,0,1,1,2,3,5,`. A lookup frames the query the same way, `,1,2,3,5,`, and asks
+which stored sequences contain that substring. Framing the run on both sides
+makes substring containment exactly the contiguous-subsequence predicate OEIS
+itself uses: term boundaries hold (`2,3` cannot match inside `23`), terms must be
+adjacent, and signs are respected. At ~370k sequences this resolves well under a
+second, so the MVP needs no inverted index.
+
+### The transforms
+
+Before matching, `oeis-seek` also tries simple transforms of your input and looks
+each result up:
+
+- **raw** - the input as given
+- **first differences** - `a(n+1) - a(n)`
+- **partial sums** - running totals
+- **consecutive ratios** - `a(n+1) / a(n)` (later over earlier), used only when
+  every ratio divides exactly, e.g. `1, 2, 6, 24` becomes `2, 3, 4`
+- **higher-order differences** - first differences applied repeatedly (orders 2
+  and 3)
+- **a(n) - n** and **a(n) / n** - subtract or divide by the 0-based index (the
+  latter integer-only)
+- **absolute values** - `abs(a(n))`, to recognize a signed sequence by magnitude
+
+Transforms live in a registry, so adding more later is one function plus one
+registration.
+
+### The ranking
+
+Every hit gets a deterministic, explainable score. Matches needing no transform
+rank above transformed ones, more matched terms rank higher, and sequences in
+OEIS's curated `core` set are boosted so canonical sequences outrank obscure ones
+that merely share a run. A run found near a sequence's opening is weak extra
+evidence over one buried deep inside, and ties resolve by ascending A-number so
+output is stable. All scoring weights live in one place, and each result tells
+you which transform found it and why it ranked where it did.
+
+## Development
+
+Lint, format, and test:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+uv run pytest
+```
+
+CI runs ruff and pytest on every push and pull request.
+
+To refresh the embedded OEIS core set:
+
+```bash
+uv run python tools/generate_core_set.py
+```

oeis_seek-0.1.0/README.md

@@ -0,0 +1,109 @@
+# oeis-seek
+
+[![CI](https://github.com/niarenaw/oeis-seek/actions/workflows/ci.yml/badge.svg)](https://github.com/niarenaw/oeis-seek/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/oeis-seek.svg)](https://pypi.org/project/oeis-seek/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Identify the OEIS sequence a list of integers belongs to - even when the raw
+numbers are not in OEIS but a simple transform of them is.
+
+`oeis-seek` works offline against a local copy of the
+[OEIS](https://oeis.org/) bulk dump. You download the dump once, then look up
+sequences with no network calls and no rate limits.
+
+## Install
+
+Install the released CLI from PyPI (the package is `oeis-seek`; it installs a
+`oeis-seek` command):
+
+```bash
+uv tool install oeis-seek    # or: pipx install oeis-seek, or: pip install oeis-seek
+```
+
+Or work from a clone:
+
+```bash
+uv sync
+```
+
+## Usage
+
+First, download and index the OEIS dump (one time; re-run to refresh):
+
+```bash
+oeis-seek update
+```
+
+Then identify a sequence:
+
+```bash
+oeis-seek 0,1,1,2,3,5,8,13          # -> A000045 (Fibonacci), raw match
+oeis-seek 2,6,12,20,30,42           # -> hit via first differences
+echo "1 2 6 24 120" | oeis-seek     # terms from stdin
+oeis-seek 2,6,12,20 --json          # machine-readable output
+oeis-seek 2,6,12,20 --limit 5       # cap results (default 10)
+```
+
+Terms may be comma- or whitespace-separated, passed as arguments or piped on
+stdin. At least four terms are required by default (`--min-terms` lowers it).
+
+## How it works
+
+Three ideas do the work.
+
+### The matcher (framed-substring contiguous match)
+
+The index stores each sequence's terms as a comma-framed string,
+`,0,1,1,2,3,5,`. A lookup frames the query the same way, `,1,2,3,5,`, and asks
+which stored sequences contain that substring. Framing the run on both sides
+makes substring containment exactly the contiguous-subsequence predicate OEIS
+itself uses: term boundaries hold (`2,3` cannot match inside `23`), terms must be
+adjacent, and signs are respected. At ~370k sequences this resolves well under a
+second, so the MVP needs no inverted index.
+
+### The transforms
+
+Before matching, `oeis-seek` also tries simple transforms of your input and looks
+each result up:
+
+- **raw** - the input as given
+- **first differences** - `a(n+1) - a(n)`
+- **partial sums** - running totals
+- **consecutive ratios** - `a(n+1) / a(n)` (later over earlier), used only when
+  every ratio divides exactly, e.g. `1, 2, 6, 24` becomes `2, 3, 4`
+- **higher-order differences** - first differences applied repeatedly (orders 2
+  and 3)
+- **a(n) - n** and **a(n) / n** - subtract or divide by the 0-based index (the
+  latter integer-only)
+- **absolute values** - `abs(a(n))`, to recognize a signed sequence by magnitude
+
+Transforms live in a registry, so adding more later is one function plus one
+registration.
+
+### The ranking
+
+Every hit gets a deterministic, explainable score. Matches needing no transform
+rank above transformed ones, more matched terms rank higher, and sequences in
+OEIS's curated `core` set are boosted so canonical sequences outrank obscure ones
+that merely share a run. A run found near a sequence's opening is weak extra
+evidence over one buried deep inside, and ties resolve by ascending A-number so
+output is stable. All scoring weights live in one place, and each result tells
+you which transform found it and why it ranked where it did.
+
+## Development
+
+Lint, format, and test:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+uv run pytest
+```
+
+CI runs ruff and pytest on every push and pull request.
+
+To refresh the embedded OEIS core set:
+
+```bash
+uv run python tools/generate_core_set.py
+```

oeis_seek-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "oeis-seek"
+version = "0.1.0"
+description = "Transform-aware identifier for OEIS integer sequences"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "niarenaw" }]
+keywords = ["oeis", "integer-sequences", "cli", "mathematics", "sequence"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "platformdirs>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/niarenaw/oeis-seek"
+Repository = "https://github.com/niarenaw/oeis-seek"
+Issues = "https://github.com/niarenaw/oeis-seek/issues"
+
+[project.scripts]
+oeis-seek = "oeis_seek.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.10",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.uv]
+# Dependency cooldown to mitigate supply-chain attacks (https://cooldowns.dev/).
+# This uv version (0.9.7) requires a fixed date rather than a relative duration,
+# so this is pinned to three days before the last dependency review and must be
+# advanced when dependencies are intentionally updated.
+exclude-newer = "2026-06-01T00:00:00Z"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oeis_seek"]

oeis_seek-0.1.0/src/oeis_seek/__init__.py

@@ -0,0 +1,7 @@
+"""oeis-seek - a transform-aware identifier for OEIS integer sequences."""
+
+from oeis_seek.core import identify
+from oeis_seek.models import Match, Result
+
+__all__ = ["identify", "Match", "Result"]
+__version__ = "0.1.0"

oeis_seek-0.1.0/src/oeis_seek/cli.py

@@ -0,0 +1,185 @@
+"""The ``oeis-seek`` command: a thin formatter over :func:`oeis_seek.core.identify`.
+
+Input parsing, the minimum-terms rule, input bounds, output formatting, and the
+``update`` subcommand all live here. Identification itself is delegated to the
+library core, so the deferred web/API/MCP surfaces reuse that core unchanged.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+from oeis_seek import core, download, index
+from oeis_seek.models import Result
+
+DEFAULT_MIN_TERMS = 4
+DEFAULT_LIMIT = 10
+MAX_TERMS = 10_000
+MAX_TERM_DIGITS = 5_000
+
+_TOKEN_SPLIT = re.compile(r"[,\s]+")
+
+
+def parse_terms(raw: str) -> list[int]:
+    """Parse comma- and/or whitespace-separated integers, with sane bounds."""
+    tokens = [t for t in _TOKEN_SPLIT.split(raw.strip()) if t]
+    if len(tokens) > MAX_TERMS:
+        raise ValueError(f"too many terms (max {MAX_TERMS})")
+    terms: list[int] = []
+    for token in tokens:
+        if len(token.lstrip("-")) > MAX_TERM_DIGITS:
+            raise ValueError(f"term too large (max {MAX_TERM_DIGITS} digits)")
+        terms.append(int(token))
+    return terms
+
+
+def _read_input(args_terms: list[str]) -> str:
+    if args_terms:
+        return " ".join(args_terms)
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    return ""
+
+
+# Field labels are padded to a fixed column so values line up down each block.
+_LABEL_WIDTH = len("confidence")
+_PREVIEW_TERMS = 8
+_BOLD = "1"  # ANSI SGR codes, applied only on a TTY
+_DIM = "2"
+
+
+def _use_color() -> bool:
+    """Color only when writing to a terminal and NO_COLOR is unset."""
+    return sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+
+def _wrap(text: str, code: str, *, enabled: bool) -> str:
+    return f"\033[{code}m{text}\033[0m" if enabled else text
+
+
+def _field(label: str, value: str) -> str:
+    return f"   {label.ljust(_LABEL_WIDTH)} {value}"
+
+
+def format_human(results: list[Result], snapshot: str, *, color: bool | None = None) -> str:
+    """Render a scannable, aligned result block per match; plain when not a TTY."""
+    enabled = _use_color() if color is None else color
+    header = f"Snapshot: {snapshot}"
+    if not results:
+        return f"{header}\n\nNo matches found."
+
+    blocks: list[str] = []
+    for i, r in enumerate(results, 1):
+        preview = ", ".join(str(t) for t in r.matched_terms[:_PREVIEW_TERMS])
+        lead = f"{i}. {_wrap(r.a_number, _BOLD, enabled=enabled)}  {r.name}"
+        blocks.append(
+            "\n".join(
+                [
+                    lead,
+                    _field("transform", r.transform),
+                    _field("confidence", f"{r.score:g}"),
+                    _field("matched", preview),
+                    _field("why", r.explanation),
+                    f"   {_wrap(r.url, _DIM, enabled=enabled)}",
+                ]
+            )
+        )
+    return f"{header}\n\n" + "\n\n".join(blocks)
+
+
+def format_json(results: list[Result], snapshot: str) -> str:
+    payload = {
+        "snapshot": snapshot,
+        "results": [
+            {
+                "a_number": r.a_number,
+                "name": r.name,
+                "transform": r.transform,
+                "confidence": r.score,
+                "matched_terms": r.matched_terms,
+                "url": r.url,
+                "explanation": r.explanation,
+            }
+            for r in results
+        ],
+    }
+    return json.dumps(payload, indent=2)
+
+
+def _run_update() -> int:
+    print("Downloading OEIS dump ...", file=sys.stderr)
+    download.download()
+    print("Building index ...", file=sys.stderr)
+    count = index.build()
+    handle = index.open_index()
+    try:
+        print(f"Indexed {count} sequences (snapshot: {handle.snapshot_date}).")
+    finally:
+        handle.close()
+    return 0
+
+
+def _run_lookup(args: argparse.Namespace) -> int:
+    raw = _read_input(args.terms)
+    if not raw.strip():
+        print("No terms given. Example: oeis-seek 2,6,12,20,30", file=sys.stderr)
+        return 2
+    try:
+        terms = parse_terms(raw)
+    except ValueError as exc:
+        print(f"Invalid input: {exc}", file=sys.stderr)
+        return 2
+
+    if len(terms) < args.min_terms:
+        print(
+            f"Need at least {args.min_terms} terms (got {len(terms)}). "
+            f"Use --min-terms to lower the threshold.",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        handle = index.open_index()
+    except FileNotFoundError:
+        print("No local data - run `oeis-seek update` first.", file=sys.stderr)
+        return 3
+
+    try:
+        results = core.identify(terms, handle, limit=args.limit)
+        snapshot = handle.snapshot_date
+    finally:
+        handle.close()
+
+    print(format_json(results, snapshot) if args.json else format_human(results, snapshot))
+    return 0 if results else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="oeis-seek",
+        description="Identify the OEIS sequence a list of integers belongs to.",
+        epilog="Run `oeis-seek update` to download and index the OEIS bulk dump.",
+    )
+    parser.add_argument("terms", nargs="*", help="integer terms (comma/space separated)")
+    parser.add_argument("--limit", type=int, default=DEFAULT_LIMIT, help="max results")
+    parser.add_argument(
+        "--min-terms", type=int, default=DEFAULT_MIN_TERMS, help="minimum input terms"
+    )
+    parser.add_argument("--json", action="store_true", help="emit JSON")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "update":
+        return _run_update()
+    args = build_parser().parse_args(argv)
+    return _run_lookup(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oeis_seek-0.1.0/src/oeis_seek/core.py

@@ -0,0 +1,63 @@
+"""The identification fan-out: the single public entry point.
+
+``identify`` normalizes the input, runs every registered transform, matches each
+candidate against the index, dedupes the same sequence to its best-scoring hit,
+and returns ranked results. Keeping the fan-out and dedup here (rather than in the
+ranking module) gives the transform loop one home and keeps ranking a pure
+function. Every future surface (CLI today; web/API/MCP later) calls this.
+"""
+
+from __future__ import annotations
+
+from oeis_seek import rank
+from oeis_seek.index import Index
+from oeis_seek.matcher import find_matches
+from oeis_seek.models import Result
+from oeis_seek.transforms import REGISTRY
+from oeis_seek.transforms.normalize import strip_leading_zeros_and_ones
+
+# Lowest-distance transforms first, computed once: a candidate produced by several
+# transforms is then scanned and attributed to its strongest (lowest-distance) one.
+_ORDERED_TRANSFORMS = sorted(REGISTRY.items(), key=lambda item: rank.distance(item[0]))
+
+
+def identify(terms: list[int], index: Index, limit: int = 10) -> list[Result]:
+    """Identify the OEIS sequences ``terms`` most likely belong to.
+
+    Runs the input and each transform of it against ``index``, ranking all hits.
+    The caller owns the index handle; acquisition (and its "no local data" error)
+    is a boundary concern, so every surface opens the index itself.
+    """
+    normalized = strip_leading_zeros_and_ones([int(t) for t in terms])
+    best: dict[str, Result] = {}
+    seen: set[tuple[int, ...]] = set()
+
+    # The seen-set skips a redundant index scan when two transforms yield the same
+    # candidate; because _ORDERED_TRANSFORMS runs lowest-distance first, the kept
+    # scan is the strongest one. Winner selection across distinct candidates is the
+    # best-per-A-number-by-score comparison below.
+    for name, transform in _ORDERED_TRANSFORMS:
+        candidate = transform(normalized)
+        if not candidate:
+            continue
+        key = tuple(candidate)
+        if key in seen:
+            continue
+        seen.add(key)
+        for match in find_matches(candidate, index):
+            result = Result(
+                a_number=match.a_number,
+                name=match.name,
+                transform=name,
+                score=rank.score(match, name),
+                matched_terms=match.matched_terms,
+                explanation=rank.explain(match, name),
+            )
+            incumbent = best.get(match.a_number)
+            if incumbent is None or result.score > incumbent.score:
+                best[match.a_number] = result
+
+    # Highest score first, ascending A-number as the deterministic tiebreak so
+    # equal-scoring results always order the same way.
+    ranked = sorted(best.values(), key=lambda r: (-r.score, r.a_number))
+    return ranked[:limit]