openppc 0.1.0__py3-none-any.whl

openppc/__init__.py

@@ -0,0 +1,3 @@
+"""OpenPPC: read-only Google Ads audits where every number is traced back to your data."""
+
+__version__ = "0.1.0"

openppc/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

openppc/checkfacts.py

@@ -0,0 +1,96 @@
+"""Facts for `openppc check`: every figure a reasonable audit of your files could cite.
+
+For each export we register the account totals, every row, and every campaign, ad group
+and match type group: cost, clicks, impressions, conversions, CTR, CPC, cost per
+conversion, conversion rate, and each one's share of the total. Then we add every number
+our own templates would print. Template thresholds are left out on purpose: a threshold
+we chose is not a fact about your account.
+"""
+from dataclasses import replace
+
+from .engine import benchmarks
+from .facts import Fact, FactBook
+from .ingest import load_report
+from .ingest.account import is_snapshot, read_json, snapshot
+from .templates import TEMPLATES, account_read, account_structure
+from .templates._common import register_group, totals
+
+ROW_KEYS = ("search_term", "keyword", "ad_group", "campaign")
+GROUP_KEYS = ("campaign", "ad_group", "match_type")
+
+
+def facts_for_report(report):
+    book = FactBook(report.currency)
+    grand = totals(report.rows)
+    register_group(book, "", grand, grand)
+    if report.days:
+        book.count("days in the date range", report.days, "days")
+    row_key = next((k for k in ROW_KEYS if report.has(k)), None)
+    never_rows, word = [], ""
+    if row_key:
+        rows_of = {}  # Google lists a search term once per campaign, ad group and match type
+        for row in report.rows:
+            if row.get(row_key):
+                rows_of.setdefault(" ".join(row[row_key].lower().split()), []).append(row)
+        start = len(book.facts)
+        for members in rows_of.values():
+            name = members[0][row_key].strip()
+            register_group(book, name, totals(members), grand)  # the term's total, as our reports print it
+            if len(members) > 1:
+                for row in members:  # and each row, as the export shows it
+                    register_group(book, name, totals([row]), grand)
+        book.facts[start:] = [replace(f, level="row") for f in book.facts[start:]]
+        word = {"search_term": "search terms", "keyword": "keywords"}.get(row_key, row_key.replace("_", " ") + "s")
+        book.count(f"{word} in this export", len(rows_of), "terms")
+        never = [members for members in rows_of.values() if totals(members).conversions == 0]
+        never_rows = [r for members in never for r in members]
+        if never:  # what audits usually call waste: every term that never converted, whatever it cost
+            zt = totals(never_rows)
+            book.count(f"{word} with no conversions", len(never), "terms")
+            book.money(f"cost of all {word} with no conversions", zt.cost, "cost")
+            book.count(f"clicks of all {word} with no conversions", zt.clicks, "clicks")
+            if grand.cost:
+                book.pct(f"cost of all {word} with no conversions as a share of total cost",
+                         zt.cost / grand.cost * 100, "cost")
+    for key in GROUP_KEYS:
+        if key != row_key and report.has(key):
+            groups = {}
+            for row in report.rows:
+                if row.get(key):
+                    groups.setdefault(row[key], []).append(row)
+            start = len(book.facts)
+            for name, members in groups.items():
+                register_group(book, name, totals(members), grand)
+                if key == "match_type" and row_key and never_rows:  # "broad match was 62% of the waste"
+                    waste = totals(never_rows).cost
+                    mine = totals([r for r in never_rows if r.get(key) == name]).cost
+                    if waste:
+                        book.pct(f"'{name}' share of the cost of {word} with no conversions", mine / waste * 100,
+                                 "cost", name)
+            book.facts[start:] = [replace(f, level="group") for f in book.facts[start:]]
+    for template in TEMPLATES.values():
+        if template.INPUT_KIND == "report" and template.accepts(report):
+            _, template_book = template.run(report)
+            book.facts.extend(template_book.facts)
+    return [f for f in book.facts if f.metric != "rule"]
+
+
+def facts_for_paths(paths, industry=None):
+    facts = []
+    for path in paths:
+        if str(path).lower().endswith(".json"):
+            raw = read_json(path)
+            if is_snapshot(raw):
+                _, book, _ = account_structure.evaluate(snapshot(raw, source=str(path)))
+            else:
+                _, book = account_read.run(account_read.load_metrics(path))
+            facts += [f for f in book.facts if f.metric != "rule"]
+        else:
+            facts += facts_for_report(load_report(path))
+    if industry:
+        b = benchmarks.lookup(industry)
+        facts += [Fact(f"{b['name']} average CPC", b["cpc"], "money", "cpc"),
+                  Fact(f"{b['name']} average CTR", b["ctr"], "pct", "ctr"),
+                  Fact(f"{b['name']} average conversion rate", b["cvr"], "pct", "cvr"),
+                  Fact(f"{b['name']} average cost per lead", b["cpl"], "money", "cpa")]
+    return facts

openppc/cli.py

@@ -0,0 +1,78 @@
+"""OpenPPC command line.
+
+    openppc templates
+    openppc industries
+    openppc audit search-term-waste exports/search_terms.csv --industry home-services
+    openppc check --audit their_audit.md --data exports/search_terms.csv
+
+Exit codes: 0 clean, 1 bad input, 2 the check found problems, 3 our own report failed
+its number check (a bug in OpenPPC).
+"""
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .checkfacts import facts_for_paths
+from .engine import benchmarks
+from .engine.trace import render_check, trace
+from .templates import TEMPLATES, run_template
+
+
+def _emit(text, out):
+    if out:
+        Path(out).write_text(text + "\n", encoding="utf-8")
+        print(f"wrote {out}", file=sys.stderr)
+    else:
+        print(text)
+
+
+def _parser():
+    ap = argparse.ArgumentParser(
+        prog="openppc", description="Read-only Google Ads audits where every number traces back to your data.")
+    ap.add_argument("--version", action="version", version=f"openppc {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+    sub.add_parser("templates", help="list the audit templates")
+    sub.add_parser("industries", help="list the benchmark industries")
+    a = sub.add_parser("audit", help="run a template on an export")
+    a.add_argument("template", choices=sorted(TEMPLATES))
+    a.add_argument("data", help="your export (.csv) or two-period totals (.json)")
+    a.add_argument("--industry", help="compare against an industry average, e.g. home-services")
+    a.add_argument("--min-cost", type=float, default=None,
+                   help="cost threshold for a waste flag (default: about $20, in the export's currency)")
+    a.add_argument("--brand", help="your brand names, comma-separated; brand terms are never flagged as waste")
+    a.add_argument("--out", help="write the report here instead of printing it")
+    c = sub.add_parser("check", help="check the numbers in any audit against your data")
+    c.add_argument("--audit", required=True, help="the audit to check (.md or .txt)")
+    c.add_argument("--data", required=True, action="append", help="an export or totals file; repeat for more")
+    c.add_argument("--industry", help="also accept this industry's published averages")
+    c.add_argument("--out", help="write the result here instead of printing it")
+    return ap
+
+
+def main(argv=None):
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "templates":
+            for t in TEMPLATES.values():
+                print(f"{t.NAME:20} {t.TIER:5} reads a {t.INPUT}\n{'':27}{t.SUMMARY}")
+            return 0
+        if args.command == "industries":
+            for key, row in benchmarks.TABLE.items():
+                print(f"{key:20} {row[0]}")
+            return 0
+        if args.command == "audit":
+            markdown, _, passed = run_template(args.template, args.data, industry=args.industry,
+                                               min_cost=args.min_cost, brand=args.brand)
+            _emit(markdown, args.out)
+            return 0 if passed else 3
+        if args.command == "check":
+            text = Path(args.audit).read_text(encoding="utf-8")
+            claims, contradictions = trace(text, facts_for_paths(args.data, args.industry))
+            _emit(render_check(claims, contradictions), args.out)
+            clean = all(c.verdict == "traced" for c in claims) and not contradictions
+            return 0 if clean else 2
+    except (ValueError, FileNotFoundError, KeyError) as e:
+        print(f"openppc: {e}", file=sys.stderr)
+        return 1
+    return 1

openppc/engine/__init__.py

@@ -0,0 +1 @@
+"""The engine: findings (the arithmetic), benchmarks (the baseline), trace (the checker)."""

openppc/engine/benchmarks.py

@@ -0,0 +1,94 @@
+"""Industry benchmarks: the public baseline an audit is compared against.
+
+Published averages from WordStream / LocaliQ, "Google Ads Benchmarks 2026": US search
+campaigns on Google Ads and Microsoft Ads, April 2025 to March 2026. Use them as a
+ballpark, never a target: they are US-only, annual averages that blend both platforms,
+and every advertiser defines a conversion differently.
+"""
+
+SOURCE = "WordStream / LocaliQ Google Ads Benchmarks 2026, US search, Apr 2025 to Mar 2026"
+
+# key: (display name, CPC, CTR %, conversion rate %, cost per lead)
+TABLE = {
+    "all": ("All industries", 5.42, 6.64, 8.18, 66.69),
+    "animals-pets": ("Animals & Pets", 4.06, 7.49, 16.22, 31.50),
+    "apparel": ("Apparel, Fashion & Jewelry", 4.44, 6.64, 4.50, 97.51),
+    "arts-entertainment": ("Arts & Entertainment", 1.63, 12.75, 5.91, 26.84),
+    "legal": ("Attorneys & Legal Services", 9.87, 5.87, 5.55, 131.63),
+    "auto-sales": ("Automotive, For Sale", 2.27, 8.28, 6.01, 44.26),
+    "auto-repair": ("Automotive, Repair, Service & Parts", 4.35, 5.56, 15.51, 29.96),
+    "beauty": ("Beauty & Personal Care", 4.62, 6.75, 10.35, 39.25),
+    "business-services": ("Business Services", 5.87, 6.10, 4.85, 93.69),
+    "career": ("Career & Employment", 5.81, 5.88, 3.05, 67.36),
+    "dental": ("Dentists & Dental Services", 8.00, 5.66, 10.67, 72.97),
+    "education": ("Education & Instruction", 4.81, 7.56, 13.14, 77.48),
+    "finance": ("Finance & Insurance", 3.39, 9.83, 2.64, 74.44),
+    "furniture": ("Furniture", 3.97, 6.57, 2.99, 106.70),
+    "health-fitness": ("Health & Fitness", 6.17, 5.81, 6.94, 67.36),
+    "home-services": ("Home & Home Improvement", 8.33, 6.47, 8.05, 90.92),
+    "industrial": ("Industrial & Commercial", 5.87, 6.57, 8.20, 75.19),
+    "personal-services": ("Personal Services", 7.17, 7.16, 12.34, 54.60),
+    "physicians": ("Physicians & Surgeons", 4.76, 6.61, 12.43, 40.04),
+    "real-estate": ("Real Estate", 3.22, 7.61, 3.70, 102.51),
+    "restaurants": ("Restaurants & Food", 2.05, 6.83, 8.05, 30.57),
+    "shopping": ("Shopping, Collectibles & Gifts", 4.14, 8.28, 4.01, 49.40),
+    "sports-recreation": ("Sports & Recreation", 2.77, 8.75, 7.69, 44.26),
+    "travel": ("Travel", 2.14, 9.32, 5.83, 44.70),
+}
+
+
+def lookup(industry):
+    key = (industry or "").strip().lower()
+    for k, (name, cpc, ctr, cvr, cpl) in TABLE.items():
+        if key in (k, name.lower()):
+            return {"key": k, "name": name, "cpc": cpc, "ctr": ctr, "cvr": cvr, "cpl": cpl}
+    raise ValueError(f"unknown industry '{industry}'. Try one of: {', '.join(TABLE)}")
+
+
+def compare(book, industry, cost, clicks, impressions, conversions, currency="USD"):
+    """The account's ratios next to the industry's averages, every figure registered in the FactBook.
+    Returns the industry row and one dict per metric the data allows. The averages are in US dollars, so an
+    account in another currency is compared on rates only (CTR, conversion rate), never on costs."""
+    b = lookup(industry)
+    dollars = (currency or "USD").upper() == "USD"
+    metrics = []
+    if clicks and dollars:
+        metrics.append(("CPC", cost / clicks, b["cpc"], "money", "cpc", True))
+    if impressions:
+        metrics.append(("CTR", clicks / impressions * 100, b["ctr"], "pct", "ctr", False))
+    if clicks:
+        metrics.append(("Conversion rate", conversions / clicks * 100, b["cvr"], "pct", "cvr", False))
+    if conversions and dollars:
+        metrics.append(("Cost per conversion", cost / conversions, b["cpl"], "money", "cpa", True))
+    rows = []
+    for name, yours, avg, kind, metric, lower_is_better in metrics:
+        if kind == "money":
+            y = book.money(f"your {name}", yours, metric)
+            a = book.money(f"{b['name']} average {name}", avg, metric)
+        else:
+            y = book.pct(f"your {name}", yours, metric, dp=2)
+            a = book.pct(f"{b['name']} average {name}", avg, metric, dp=2)
+        rows.append({"name": name, "yours": yours, "average": avg, "yours_text": y, "average_text": a,
+                     "side": "lower" if yours < avg else "higher",
+                     "better": (yours < avg) if lower_is_better else (yours > avg)})
+    return b, rows
+
+
+def section(book, industry, cost, clicks, impressions, conversions, currency="USD"):
+    """Markdown lines comparing account ratios with the industry averages.
+    Every figure is registered in the FactBook, so the checker can trace it."""
+    b, rows = compare(book, industry, cost, clicks, impressions, conversions, currency)
+    lines = ["", f"## Against the {b['name']} average", "",
+             f"_Source: {SOURCE}. A ballpark, not a target: US-only, averaged over a year, and "
+             "every advertiser counts conversions differently. The industry figure for cost per "
+             "conversion is cost per lead._", ""]
+    if (currency or "USD").upper() != "USD":
+        lines += [f"_This account is in {currency.upper()} and the averages are in US dollars, so cost per click "
+                  "and cost per conversion are left out._", ""]
+    if not rows:
+        return lines
+    lines += ["| Metric | Yours | Industry average | Read |", "|---|---|---|---|"]
+    for r in rows:
+        lines.append(f"| {r['name']} | {r['yours_text']} | {r['average_text']} | "
+                     f"{r['side']} ({'better' if r['better'] else 'worse'}) |")
+    return lines

openppc/engine/findings.py

@@ -0,0 +1,223 @@
+"""Findings block: the arithmetic and the pattern read, done in code, before any model.
+
+WHY: when we tested language models on real Google Ads accounts, they reversed spend,
+reach and CPA directions and invented figures, even after fine-tuning. Those are not
+language tasks. This module computes every delta, names every direction, classifies
+the account pattern with explicit rules, and hands any writer a block of facts it
+cannot get wrong.
+
+The rules are a media buyer's playbook. Read them, argue with them, send a PR.
+
+Ported from the Second Step audit engine (September 2026). Every threshold is a named
+constant below, and each one has a row in rulebook/rules.csv saying where it comes from.
+
+Usage:
+    from openppc.engine.findings import build_findings
+    block = build_findings(dict(cs=460, ps=1144, ci=11238, pi=38647, cc=279, pc=640,
+                                cv=41, pv=50), meta=dict(currency="USD",
+                                business_model="sailing club (membership lead-gen)"))
+"""
+
+FLAT = 0.03             # |change| below this is "flat"
+SMALL_SAMPLE = 10       # fewer conversions than this in BOTH periods: do not trend CPA
+NOISE_VOLUME = 50       # under this many conversions a period...
+NOISE_MOVE = 0.10       # ...a conversion move smaller than this is one or two events: flat
+HELD = 0.20             # spend cut and conversions within this of prior: they held
+CPA_BAND = 0.10         # CPA within this of prior: efficiency held
+DILUTION_REACH = 0.50   # impressions up at least this much...
+DILUTION_CTR = 0.70     # ...while CTR fell to this share of prior or less: reach dilution
+TIGHTEN_REACH = 0.30    # impressions down at least this much...
+TIGHTEN_CTR = 1.30      # ...while CTR rose to this multiple of prior or more: tightening
+CVR_DROP = 0.70         # conversion rate at or below this share of prior...
+CVR_DROP_CLICKS = 200   # ...on at least this many clicks
+MICRO_CVR = 0.25        # this share of clicks converting: engagement actions, not outcomes
+THIN_DATA = 30          # conversions a period Google wants before automated bidding is judged
+SEASONAL_WORDS = ("seasonal", "rafting", "ski", "charter")
+
+
+def _pct(c, p):
+    if not p:
+        return None
+    return (c - p) / p
+
+
+def _dir(c, p):
+    d = _pct(c, p)
+    if d is None:
+        return "n/a"
+    if abs(d) < FLAT:
+        return "flat"
+    return "up" if d > 0 else "down"
+
+
+def _fmt(v, dp=0):
+    if v is None:
+        return "n/a"
+    return f"{v:,.{dp}f}"
+
+
+def _pc(c, p):
+    d = _pct(c, p)
+    if d is None:
+        return ""
+    if abs(d) < FLAT:
+        return " (flat)"
+    return f" ({'+' if d > 0 else '-'}{abs(d) * 100:.0f}%)"
+
+
+def _line(name, c, p, dp=0, unit="", lower_is_better=False):
+    """'Spend: 460, from 1,144. DOWN 60%.'  Direction word is explicit and upper-case."""
+    d = _dir(c, p)
+    word = {"up": "UP", "down": "DOWN", "flat": "FLAT", "n/a": "no prior base"}[d]
+    tail = "" if d in ("flat", "n/a") else f" {abs(_pct(c, p)) * 100:.0f}%"
+    verdict = ""
+    if lower_is_better and d in ("up", "down"):
+        verdict = " (improved)" if d == "down" else " (worse)"
+    return f"- {name}: {_fmt(c, dp)}{unit}, from {_fmt(p, dp)}{unit}. {word}{tail}{verdict}."
+
+
+def classify(m):
+    """Return (primary_read, flags[]) from the eight raw metrics. Rules in priority order."""
+    cs, ps, ci, pi, cc, pc, cv, pv = (m[k] for k in ("cs", "ps", "ci", "pi", "cc", "pc", "cv", "pv"))
+    cpa_c = cs / cv if cv else None
+    cpa_p = ps / pv if pv else None
+    ctr_c = cc / ci if ci else 0
+    ctr_p = pc / pi if pi else 0
+    cvr_c = cv / cc if cc else 0
+    cvr_p = pv / pc if pc else 0
+    sp = _dir(cs, ps)
+    cv_d = _dir(cv, pv)
+    if max(cv, pv) < NOISE_VOLUME and _pct(cv, pv) is not None and abs(_pct(cv, pv)) < NOISE_MOVE:
+        cv_d = "flat"
+    cpa_d = _dir(cpa_c, cpa_p) if (cpa_c and cpa_p) else "n/a"
+    flags = []
+
+    # ---- primary read: first matching rule wins ------------------------------------
+    if cv == 0 and pv == 0:
+        read = ("NO TRACKED CONVERSIONS IN EITHER PERIOD. Verify tracking before reading "
+                "performance. Every cost figure here is meaningless until it fires.")
+    elif cv == 0:
+        read = (f"CONVERSIONS WENT TO ZERO, from {_fmt(pv, 1)}, on {sp} spend. Tracking is "
+                "the first suspect, before any performance conclusion.")
+    elif pv == 0:
+        read = (f"CONVERSIONS APPEARED FROM ZERO ({_fmt(cv, 1)}). Either tracking started "
+                "working or the account did. Confirm which before crediting the account.")
+    elif max(cv, pv) < SMALL_SAMPLE:
+        read = (f"SAMPLE TOO SMALL: {_fmt(cv, 1)} vs {_fmt(pv, 1)} conversions. Direction is "
+                "noise at this volume. Do not read CPA movement as a trend or act on it.")
+    elif sp == "down" and -HELD <= _pct(cv, pv) <= FLAT and cpa_d == "down":
+        read = (f"EFFICIENCY WIN. Spend cut {abs(_pct(cs, ps)) * 100:.0f}%, conversions held at "
+                f"{cv / pv * 100:.0f}% of prior, CPA improved {abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. "
+                "Volume is the constraint, not efficiency. Falling conversions here are a GOOD outcome.")
+    elif sp == "down" and _pct(cv, pv) < -HELD and cpa_d == "down":
+        read = (f"EFFICIENT CONTRACTION. Spend cut {abs(_pct(cs, ps)) * 100:.0f}% and conversions fell "
+                f"{abs(_pct(cv, pv)) * 100:.0f}%, less than spend, so CPA improved "
+                f"{abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. The cut removed waste first. Volume is now the constraint; "
+                "the falling conversion count is the price of the efficiency, not a failure.")
+    elif sp == "down" and cv_d == "down" and (cpa_d in ("flat", "n/a") or
+            (cpa_c and cpa_p and abs(_pct(cpa_c, cpa_p)) <= CPA_BAND)):
+        read = ("BUDGET REDUCTION, EFFICIENCY HELD. Spend, clicks and conversions fell together; "
+                f"CPA moved within {CPA_BAND * 100:.0f}%. Volume fell because spend fell, not because performance broke.")
+    elif sp == "down" and cv_d == "down" and cpa_d == "up":
+        read = (f"CONTRACTION WITH WORSENING EFFICIENCY. Spend down {abs(_pct(cs, ps)) * 100:.0f}% "
+                f"but conversions fell faster ({abs(_pct(cv, pv)) * 100:.0f}%), so CPA rose "
+                f"{abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. The cut removed converting volume, not just waste.")
+    elif sp in ("up", "flat") and cv_d == "down" and cpa_d == "up":
+        if sp == "up":
+            read = (f"OVER-EXPANSION. Spend up {abs(_pct(cs, ps)) * 100:.0f}% while conversions fell "
+                    f"{abs(_pct(cv, pv)) * 100:.0f}%; CPA up {abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. "
+                    "More money bought worse traffic, or the funnel broke after the click. This is the worst pattern.")
+        else:
+            read = (f"DETERIORATION AFTER THE CLICK. Spend flat, conversions down "
+                    f"{abs(_pct(cv, pv)) * 100:.0f}%, CPA up {abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. "
+                    "Traffic volume is similar; what changed is landing page, form, offer or tracking, not targeting.")
+    elif cv_d == "up" and cpa_d == "down":
+        read = (f"EFFICIENCY GAIN. Conversions up {abs(_pct(cv, pv)) * 100:.0f}% and CPA down "
+                f"{abs(_pct(cpa_c, cpa_p)) * 100:.0f}% on {sp} spend. More output at lower cost.")
+    elif cv_d == "up" and sp == "up" and cpa_d == "up":
+        read = (f"GROWTH AT A WORSENING RATE. Conversions up {abs(_pct(cv, pv)) * 100:.0f}% but spend up "
+                f"{abs(_pct(cs, ps)) * 100:.0f}% and CPA up {abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. "
+                "The marginal conversion costs far more than the average. Growth is real; efficiency is degrading.")
+    elif cv_d == "up" and cpa_d in ("flat", "n/a"):
+        read = (f"CLEAN SCALE. Conversions up {abs(_pct(cv, pv)) * 100:.0f}% with CPA flat. "
+                "Spend and output grew together at stable efficiency.")
+    elif cv_d == "flat" and cpa_d == "up":
+        read = (f"PAYING MORE FOR THE SAME. Conversions flat, CPA up {abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. "
+                "Extra spend or reach returned nothing.")
+    elif cv_d == "flat" and cpa_d == "down":
+        read = (f"SAME OUTPUT, CHEAPER. Conversions flat, CPA down {abs(_pct(cpa_c, cpa_p)) * 100:.0f}%. "
+                "Efficiency improved without volume changing.")
+    else:
+        read = "MIXED OR FLAT. No single dominant pattern; read the metric lines individually."
+
+    # ---- secondary flags: independent of the primary read ---------------------------
+    if _pct(ci, pi) is not None and _pct(ci, pi) >= DILUTION_REACH and ctr_p and ctr_c / ctr_p <= DILUTION_CTR:
+        flags.append(f"REACH DILUTION: impressions up {_pct(ci, pi) * 100:.0f}% while CTR fell from "
+                     f"{ctr_p * 100:.2f}% to {ctr_c * 100:.2f}%. Broad matching or audience expansion is buying low-intent reach.")
+    if _pct(ci, pi) is not None and _pct(ci, pi) <= -TIGHTEN_REACH and ctr_p and ctr_c / ctr_p >= TIGHTEN_CTR:
+        flags.append(f"TIGHTENING: reach cut {abs(_pct(ci, pi)) * 100:.0f}% while CTR rose from "
+                     f"{ctr_p * 100:.2f}% to {ctr_c * 100:.2f}%. Targeting narrowed and relevance improved.")
+    if cvr_p and cvr_c / cvr_p <= CVR_DROP and cc >= CVR_DROP_CLICKS:
+        flags.append(f"CONVERSION RATE fell from {cvr_p * 100:.2f}% to {cvr_c * 100:.2f}%. "
+                     "Clicks are converting worse; suspect landing page, offer, tracking, or click quality.")
+    if cvr_c >= MICRO_CVR:
+        flags.append(f"MICRO-CONVERSIONS LIKELY: {cvr_c * 100:.0f}% of clicks convert. These are engagement "
+                     "actions, not outcomes. Do not read CPA as cost per lead or booking.")
+    if 0 < max(cv, pv) < THIN_DATA:
+        flags.append(f"THIN DATA: under {THIN_DATA} conversions a period is too few to judge automated bidding on.")
+    return read, flags
+
+
+def biggest_move(m):
+    """Which metric moved most, dollar-weighted: CPA and conversions outrank reach."""
+    cs, ps, cv, pv = m["cs"], m["ps"], m["cv"], m["pv"]
+    cpa_c = cs / cv if cv else None
+    cpa_p = ps / pv if pv else None
+    cands = []
+    if cpa_c and cpa_p:
+        cands.append(("CPA", _pct(cpa_c, cpa_p)))
+    if pv:
+        cands.append(("conversions", _pct(cv, pv)))
+    if ps:
+        cands.append(("spend", _pct(cs, ps)))
+    if not cands:
+        return "not computable"
+    name, d = max(cands, key=lambda x: abs(x[1]))
+    return f"{name} {'up' if d > 0 else 'down'} {abs(d) * 100:.0f}%"
+
+
+def build_findings(m, meta=None):
+    meta = meta or {}
+    cs, ps, ci, pi, cc, pc, cv, pv = (m[k] for k in ("cs", "ps", "ci", "pi", "cc", "pc", "cv", "pv"))
+    cpa_c = cs / cv if cv else None
+    cpa_p = ps / pv if pv else None
+    ctr_c = cc / ci * 100 if ci else 0
+    ctr_p = pc / pi * 100 if pi else 0
+    read, flags = classify(m)
+    bm = (meta.get("business_model") or "").lower()
+    if any(w in bm for w in SEASONAL_WORDS):
+        flags.append("SEASONAL BUSINESS: period-over-period is the wrong lens. Most of any change is the "
+                     "calendar. Compare against the same period last year before crediting the account.")
+    cur = meta.get("currency", "USD")
+    if cur and cur.upper() != "USD":
+        flags.append(f"CURRENCY IS {cur.upper()}: do not compare these figures to USD accounts.")
+
+    lines = [
+        "COMPUTED FINDINGS (facts, already calculated; restate them, never recompute or reverse them):",
+        _line("Spend", cs, ps),
+        _line("Impressions", ci, pi),
+        _line("Clicks", cc, pc),
+        f"- CTR: {ctr_c:.2f}%, from {ctr_p:.2f}%. {_dir(ctr_c, ctr_p).upper()}.",
+        _line("Conversions", cv, pv, dp=1 if (cv % 1 or pv % 1) else 0),
+        (_line("CPA", cpa_c, cpa_p, dp=2, lower_is_better=True)
+         if (cpa_c and cpa_p) else f"- CPA: {_fmt(cpa_c, 2)}, from {_fmt(cpa_p, 2)}."),
+        "",
+        f"READ: {read}",
+        f"BIGGEST MOVE: {biggest_move(m)}",
+    ]
+    if flags:
+        lines.append("FLAGS:")
+        lines += [f"- {f}" for f in flags]
+    else:
+        lines.append("FLAGS: none")
+    return "\n".join(lines)