Returns each match with its UKPRN, the key that every other tool uses to
identify a provider. Use this first when the user names a university
loosely — "UCL", "Sheffield Uni" and "Manchester Met" all resolve.
Universities rank above colleges when a fragment matches both.

Covers the ~450 providers that appear in the National Student Survey.
It cannot tell you about providers with no published NSS results (very
small or new providers are often suppressed).

Returns positivity scores (the % of students answering positively) per
question and theme, with two comparators: the OfS benchmark (the score a
provider with this mix of students and subjects would be expected to get,
including whether the provider is materially above or below it) and the
UK sector average on the same cut. A score without its benchmark is
misleading; always quote both.

Args:
    ukprn: Provider id from search_providers.
    subject: Optional CAH subject name filter, e.g. "Law", "Nursing"
        (matches partially). Omit for provider-level results.
    question: Optional filter on question/theme text, e.g. "feedback",
        "Theme 3", "Q14". Omit for everything.
    subject_level: Granularity of the subject cut when `subject` is given:
        "CAH1" (broadest, ~23 groups), "CAH2" (default, ~35 groups) or
        "CAH3" (finest, ~100+). Without this the same subject would appear
        once per level.
    population: "Registered" (default; the OfS headline convention) or
        "Taught".
    mode_of_study: "All modes" (default), "Full-time", "Part-time" or
        "Apprenticeship".
    level_of_study: "First degree" (default), "Other undergraduate",
        "Undergraduate with postgraduate component" or
        "All undergraduates".

This is survey data about the student experience. It cannot tell you
application volumes, offer rates, entry requirements or fees — none of
that is in the NSS. Say so rather than inferring it from satisfaction.

Returns one entry per question/theme, each holding every provider's
positivity score, its OfS benchmark and its position against it, plus the
UK sector average for context. Because each provider is judged against
its own benchmark, this comparison is fairer than ranking raw scores —
say which providers beat their benchmark, not just who scored highest.

Args:
    ukprns: Two or more provider ids from search_providers.
    subject: Optional CAH subject name filter, e.g. "Computing". Omit to
        compare at whole-provider level.
    question: Filter on question/theme text. Defaults to "Theme" (the
        seven headline themes), which keeps the comparison readable.
        Pass None (or a specific question) to widen or narrow it.
    subject_level, population, mode_of_study, level_of_study: As in
        nss_scores.

A provider missing from a row has suppressed data on that cut (under 10
respondents) — report the gap, don't fill it.

Three indicators, each a percentage of students:
  - Continuation: still in higher education (or qualified) about a year
    after starting.
  - Completion: qualified or still studying four years after starting.
  - Progression: in managerial/professional employment or further study
    15 months after graduating.

Each row carries the OfS benchmark (expected value given the provider's
student and course mix), the regulatory minimum threshold the OfS
enforces (condition B3), and the number of students behind the figure.
Quote outcomes against the benchmark, not just the raw percentage. Years
are pooled windows (e.g. "2019-2022") — the latest available per
indicator is returned.

Args:
    ukprn: Provider id from search_providers.
    indicator: Optional filter — "Continuation", "Completion" or
        "Progression" (partial match). Omit for all three.
    subject: Optional subject filter by CAH name ("Law") or code
        ("CAH16-01"). Omit for whole-provider figures.
    split_type: Optional demographic split instead of subject — e.g.
        "Sex", "Ethnicity", "AgeOnCommencement", "Disability",
        "DeprivationQuintile". Use with or without split_value.
    split_value: Optional value within the split, e.g. "Female",
        "Mature". Partial match.
    mode: "Full-time" (default), "Part-time" or "Apprenticeship".
    level: "FirstDegree" (default), "AllUndergraduates",
        "OtherUndergraduate", "PostgraduateTaughtMasters",
        "PostgraduateResearch", "PGCE" and others.

A NULL value with a supp_reason (e.g. "[low]") means the OfS suppressed
that figure, usually for small numbers — report the suppression, don't
estimate. This dataset has no application volumes, entry grades or
satisfaction scores (NSS tools cover satisfaction).

Returns lower-quartile, median and upper-quartile annualised earnings at
1, 3 and 5 years after graduation, by CAH2 subject, with the UK-wide
figure on the same cut for context. Always quote the median with its
quartiles — the spread is usually the story — and say how many graduates
the figure is based on.

Args:
    ukprn: Provider id from search_providers.
    subject: Optional CAH2 subject name filter, e.g. "Law", "Computing"
        (partial match). Omit for all subjects.
    years_after: 1, 3 or 5 (years after graduation). Omit for all three.
    tax_year: e.g. "2022/2023". Omit for the latest available.
    characteristic_type: "All graduates" (default), or a split:
        "sex", "ethnicity", "POLAR4", "prior_attainment_code".
    characteristic_value: Value within the split, e.g. "F", "M".

Honest limits, worth repeating to the user: these are pre-tax earnings of
UK graduates in sustained employment whose records matched tax data —
the self-employed abroad, or those out of work, aren't in the medians.
Earnings reflect where graduates live and work (London weighting is
real), and nothing here is causal: a subject's high earnings may be who
it admits, not what it teaches. No figures on application volumes,
satisfaction or dropout — other tools cover the latter two.