@rubytech/create-maxy-code 0.1.58 → 0.1.60

package/payload/platform/plugins/preval/skills/property-preval/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: property-preval
+description: Use when an operator asks for a pre-valuation pack for a single UK property — input is one full UK address, output is a 4-page A4 PDF covering valuation, area, and demand/trend. Triggers include "preval <address>", "pre-valuation for <address>", "what's <address> worth", "valuation pack for <address>", "market and area report for <address>".
+---
+
+# Property Preval
+
+Outcome: turn **one full UK address** into a 4-page A4 pre-valuation PDF the operator can send to a vendor before the appraisal visit. The skill owns the fan-out and the render; the operator supplies only the address.
+
+## Input
+
+A single string — the full UK address, ending in a valid UK postcode. Examples:
+
+- `47 Phoenix Drive, Bishop's Stortford, CM23 2UJ`
+- `Flat 3, 122 Kensington High Street, London, W8 4SG`
+
+The skill derives the postcode by matching the UK postcode regex on the final token group. If no postcode is matched, the skill stops and asks the operator for one.
+
+## Output
+
+A directory under `~/Documents/Maxy/preval/<postcode-compact>-<YYYY-MM-DD>/` containing:
+
+- `index.html` — single self-contained file.
+- `<slug>-<date>.pdf` — exactly 4 A4 pages. If `mdls -name kMDItemNumberOfPages` returns ≠ 4, the renderer raises rather than ship an overflowing report.
+
+Return the PDF path to the operator.
+
+## Tools the skill calls (in order)
+
+Fan-out is fixed at **12** `real-agent-property-data` MCP tools, keyed on the derived postcode (and address attributes where the tool needs them):
+
+1. `property-data-prices` — asking £ distribution + raw asking comps.
+2. `property-data-prices-per-sqf` — asking £/sqft.
+3. `property-data-sold-prices` — Land Registry sold transactions + raw sold comps.
+4. `property-data-sold-prices-per-sqf` — achieved £/sqft.
+5. `property-data-growth` — 7y price series.
+6. `property-data-growth-psf` — 7y £/sqft series.
+7. `property-data-demand` — for-sale, sales/mo, turnover, MoI, DoM, demand rating.
+8. `property-data-demand-rent` — rental-side demand pillar.
+9. `property-data-property-types` — mix doughnut (detached / semi / terraced / flat).
+10. `property-data-crime` — area crime rating + breakdown.
+11. `property-data-flood-risk` — area flood risk (full postcode only).
+12. `property-data-council-tax` — band D cost + per-property bands (full postcode only).
+
+## Tools the skill deliberately does NOT call
+
+- `property-data-address-match-uprn` — UPRN is CRM hygiene, not preval data.
+- `property-data-planning-applications` — planning is a separate dev-precedent report.
+
+Both remain available via the underlying `property-data` skill; preval omits them to keep the output focused and the credit cost at 12 per pack.
+
+## How to execute
+
+1. Match the postcode out of the address (`/[A-Z]{1,2}[0-9][A-Z0-9]?\s?[0-9][A-Z]{2}/i`). Stop and ask if no match.
+2. Run the 12 fan-out tools in the order above. Any `Error: key-not-registered` aborts the run — surface the registration prompt and stop.
+3. Assemble the `inputs.json` shape per `references/template-inputs.schema.json`.
+4. Run `python3 references/render.py inputs.json`. The renderer fills the template, writes the HTML, drives Chrome `--print-to-pdf`, and asserts page count = 4.
+5. Return the PDF path.
+
+## Observability
+
+Emit at start: `[preval] start address="<addr>" postcode=<pc>`.
+Emit at done:  `[preval] done pdf=<path> pages=<n> ms=<n>`.
+
+Each of the 12 fan-out calls produces its own `[property-data] tool=<name>` line in `server.log` (inherited contract — no new instrumentation).
+
+## Failure signatures
+
+- `pages=5` (or anything ≠ 4) in the `done` line → template overflow on one page. Diagnose with `pdftoppm -png -f 5 -l 5 <pdf>` to see which content bled, then trim that panel's padding.
+- `start` with no matching `done` within 60s → renderer crashed. Inspect with `grep -B2 -A20 '\[preval\] start address="<echoed>"' server.log`.
+- Wrong postcode derivation → check `grep '\[preval\] start' server.log | awk -F'postcode=' '{print $2}' | sort -u`; the regex must keep the inward part of the postcode (e.g. `CM23 2UJ`, not `CM23`).
+
+## Out of scope
+
+- Multi-address batch preval (CSV in → many PDFs out) — separate skill if needed.
+- Loop CRM auto-publish of the PDF onto a contact's record — separate skill.
+- A hero image on the cover via `property-socials` — preval cover is text-only by design.
+- Caching of MCP responses — 12 credits per pack is acceptable; cost optimisation is a Task 144B concern.

package/payload/platform/plugins/preval/skills/property-preval/references/render.py

@@ -0,0 +1,265 @@
+"""property-preval renderer.
+
+Substitutes <!-- REPLACE: <slot> --> placeholders in template.html with values
+derived from one inputs.json (shape: template-inputs.schema.json), drives
+Chrome headless to produce a 4-page A4 PDF, and asserts page count == 4.
+
+Usage:
+    python3 render.py inputs.json
+"""
+from __future__ import annotations
+import html, json, re, shutil, subprocess, sys
+from pathlib import Path
+
+
+def _money(n: int) -> str:
+    return f"£{int(n):,}"
+
+
+def _sold_comps_rows(rows: list[dict]) -> str:
+    if not rows:
+        return '<tr><td colspan="4" class="muted">No sold transactions in the sample.</td></tr>'
+    return "".join(
+        f"<tr><td>{html.escape(r['date'])}</td>"
+        f"<td>{html.escape(r['address'])}</td>"
+        f"<td>{html.escape(r['type'])}</td>"
+        f"<td class=\"num\">{_money(r['price'])}</td></tr>"
+        for r in rows[:6]
+    )
+
+
+def _asking_comps_tiles(rows: list[dict]) -> str:
+    if not rows:
+        return '<div class="muted">No live asking comps in the sample.</div>'
+    out = []
+    for r in rows[:4]:
+        meta_bits = []
+        if r.get("beds"):
+            meta_bits.append(f"{r['beds']} bed")
+        if r.get("type"):
+            meta_bits.append(html.escape(r["type"]))
+        meta = " · ".join(meta_bits) or "&nbsp;"
+        out.append(
+            f'<div class="ask-tile">'
+            f'<div class="addr">{html.escape(r["address"])}</div>'
+            f'<div class="price">{_money(r["price"])}</div>'
+            f'<div class="meta">{meta}</div>'
+            f"</div>"
+        )
+    return "".join(out)
+
+
+def _crime_rows(rows: list[dict]) -> str:
+    if not rows:
+        return '<div class="muted">No crime data.</div>'
+    top = sorted(rows, key=lambda r: r["count"], reverse=True)[:6]
+    cap = max((r["count"] for r in top), default=1) or 1
+    return "".join(
+        f'<div class="dist-row">'
+        f'<div class="name">{html.escape(r["category"])}</div>'
+        f'<div class="bar"><span{" class=gold" if i == 0 else ""} style="width:{int(100 * r["count"] / cap)}%"></span></div>'
+        f'<div class="pct">{r["count"]}</div>'
+        f"</div>"
+        for i, r in enumerate(top)
+    )
+
+
+def _band_rows(rows: list[dict]) -> str:
+    if not rows:
+        return '<tr><td colspan="2" class="muted">No banding data.</td></tr>'
+    return "".join(
+        f"<tr><td>Band {html.escape(r['band'])}</td>"
+        f"<td class=\"num\">{_money(r['amount'])}</td></tr>"
+        for r in rows
+    )
+
+
+def _type_dist_rows(rows: list[dict]) -> str:
+    if not rows:
+        return '<div class="muted">No property-type mix data.</div>'
+    ordered = sorted(rows, key=lambda r: float(r["pct"]), reverse=True)
+    return "".join(
+        f'<div class="dist-row">'
+        f'<div class="name">{html.escape(r["name"])}</div>'
+        f'<div class="bar"><span{" class=gold" if i == 0 else ""} style="width:{float(r["pct"]):.0f}%"></span></div>'
+        f'<div class="pct">{float(r["pct"]):.1f}%</div>'
+        f"</div>"
+        for i, r in enumerate(ordered)
+    )
+
+
+def _spark_svg(price_series: list[dict], psf_series: list[dict]) -> str:
+    """Two-line sparkline in a 1000x380 viewBox SVG, no external dependencies."""
+    W, H = 1000, 380
+    pad_l, pad_r, pad_t, pad_b = 70, 30, 30, 50
+    iw, ih = W - pad_l - pad_r, H - pad_t - pad_b
+
+    def _line(series, key, css_pl, css_pt):
+        if not series:
+            return ""
+        ys = [float(p[key]) for p in series]
+        ymin, ymax = min(ys), max(ys)
+        if ymax == ymin:
+            ymax = ymin + 1
+        n = len(series)
+        pts = []
+        circles = []
+        labels = []
+        for i, p in enumerate(series):
+            x = pad_l + (i * iw / max(1, n - 1))
+            y = pad_t + ih - ((float(p[key]) - ymin) / (ymax - ymin)) * ih
+            pts.append(f"{x:.1f},{y:.1f}")
+            circles.append(f'<circle class="{css_pt}" cx="{x:.1f}" cy="{y:.1f}" r="3"/>')
+            labels.append(
+                f'<text x="{x:.1f}" y="{H - 18}" text-anchor="middle">{html.escape(p["label"])}</text>'
+            )
+        return (
+            f'<polyline class="{css_pl}" points="{" ".join(pts)}"/>'
+            + "".join(circles)
+            + "".join(labels)
+        )
+
+    axis = (
+        f'<line class="axis" x1="{pad_l}" y1="{pad_t + ih}" x2="{W - pad_r}" y2="{pad_t + ih}"/>'
+    )
+    body = axis + _line(price_series, "price", "pl", "pt") + _line(psf_series, "psf", "pl-psf", "pt-psf")
+    return (
+        f'<svg class="spark" viewBox="0 0 {W} {H}" preserveAspectRatio="none" xmlns="http://www.w3.org/2000/svg">{body}</svg>'
+    )
+
+
+def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Path:
+    template_path = template_path or (Path(__file__).parent / "template.html")
+    tmpl = template_path.read_text()
+
+    v = inputs["valuation"]
+    a = inputs["area"]
+    d = inputs["demand_trend"]
+    r = d["rental"]
+
+    slots = {
+        "address":            inputs["address"],
+        "postcode":           inputs["postcode"],
+        "generated":          inputs["generated"],
+
+        "kpi_avg_asking":     _money(v["avg_asking"]),
+        "kpi_asking_psf":     _money(v["asking_psf"]),
+        "kpi_avg_sold":       _money(v["avg_sold"]),
+        "kpi_sold_psf":       _money(v["sold_psf"]),
+        "sold_comps_rows":    _sold_comps_rows(v.get("sold_comps", [])),
+        "asking_comps_tiles": _asking_comps_tiles(v.get("asking_comps", [])),
+
+        "area_headline":      a["headline"],
+        "kpi_crime":          a["crime_rating"],
+        "kpi_flood":          a["flood_risk"],
+        "kpi_band_d":         _money(a["council_tax_band_d"]),
+        "kpi_population":     f"{int(a['population']):,}",
+        "crime_rows":         _crime_rows(a.get("crime_breakdown", [])),
+        "band_rows":          _band_rows(a.get("council_tax_bands", [])),
+
+        "kpi_demand_rating":  d["demand_rating"],
+        "kpi_dom":            str(d["dom"]),
+        "kpi_turnover":       f"{int(d['turnover_pct'])}%",
+        "kpi_for_sale":       str(d["for_sale"]),
+        "spark_svg":          _spark_svg(d.get("growth_series", []), d.get("growth_psf_series", [])),
+
+        "rental_rating":      r["demand_rating"],
+        "rental_dom":         str(r["dom"]),
+        "rental_turnover":    f"{int(r['turnover_pct'])}%",
+        "rental_for_rent":    str(r["for_rent"]),
+
+        "type_dist_rows":     _type_dist_rows(d.get("type_dist", [])),
+    }
+
+    # Escape free-form text slots that aren't already HTML fragments.
+    text_slots = {"address", "postcode", "generated", "area_headline", "kpi_crime", "kpi_flood",
+                  "kpi_demand_rating", "rental_rating"}
+    for k in text_slots:
+        slots[k] = html.escape(slots[k])
+
+    out = tmpl
+    for k, val in slots.items():
+        out = out.replace(f"<!-- REPLACE: {k} -->", val)
+
+    leftovers = re.findall(r"<!-- REPLACE: (\w+) -->", out)
+    if leftovers:
+        raise RuntimeError(
+            "template has unfilled placeholders: " + ", ".join(sorted(set(leftovers)))
+        )
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "index.html"
+    out_path.write_text(out)
+    return out_path
+
+
+def render_pdf(out_dir: Path, pdf_name: str) -> Path:
+    chrome = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    if not Path(chrome).exists():
+        raise FileNotFoundError(
+            "Chrome not found at " + chrome + " — install Chrome or override the path."
+        )
+    pdf_path = out_dir / pdf_name
+    subprocess.run([
+        chrome, "--headless", "--disable-gpu", "--no-pdf-header-footer",
+        f"--print-to-pdf={pdf_path.resolve()}", "--virtual-time-budget=30000",
+        f"file://{(out_dir / 'index.html').resolve()}",
+    ], check=True, capture_output=True)
+    return pdf_path
+
+
+_PAGE_OBJ_RE = re.compile(rb"/Type\s*/Page(?![sA-Za-z])")
+
+
+def _count_pages(pdf_path: Path) -> int:
+    """Prefer pdfinfo (handles compressed object streams); fall back to a
+    raw `/Type /Page` byte scan when pdfinfo is not installed. The fallback
+    is correct for current Chrome `--print-to-pdf` output (no `/ObjStm`)
+    but would silently undercount if a future Chrome switches to compressed
+    page-object streams — hence pdfinfo first when available.
+    """
+    pdfinfo = shutil.which("pdfinfo")
+    if pdfinfo:
+        result = subprocess.run(
+            [pdfinfo, str(pdf_path)], check=True, capture_output=True, text=True,
+        )
+        for line in result.stdout.splitlines():
+            if line.startswith("Pages:"):
+                return int(line.split(":", 1)[1].strip())
+        raise RuntimeError(f"pdfinfo emitted no Pages line for {pdf_path}")
+    return len(_PAGE_OBJ_RE.findall(pdf_path.read_bytes()))
+
+
+def assert_page_count(pdf_path: Path, expected: int) -> int:
+    """Assert PDF page count == expected; raise RuntimeError otherwise.
+
+    Synchronous and reliable — does not depend on Spotlight (`mdls` returns
+    `(null)` until indexing finishes, which is async). Operators can still
+    verify externally with `mdls -name kMDItemNumberOfPages <pdf>` once
+    Spotlight catches up.
+    """
+    n = _count_pages(pdf_path)
+    if n != expected:
+        raise RuntimeError(
+            f"page-count mismatch: expected {expected}, got {n} ({pdf_path}) — "
+            "tighten panel padding for the overflowing page"
+        )
+    return n
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: render.py <inputs.json>", file=sys.stderr)
+        sys.exit(2)
+    inputs = json.loads(Path(sys.argv[1]).read_text())
+    out_dir = Path(inputs["out_dir"]).expanduser()
+    base = inputs["filename_stem"]
+    render(inputs, out_dir)
+    pdf = render_pdf(out_dir, f"{base}.pdf")
+    pages = assert_page_count(pdf, 4)
+    print(f"HTML  → {out_dir/'index.html'}")
+    print(f"PDF   → {pdf} ({pages} pages)")
+
+
+if __name__ == "__main__":
+    main()

package/payload/platform/plugins/preval/skills/property-preval/references/template-inputs.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "property-preval inputs",
+  "description": "Single-source contract for render.py. Mirrors the 12 property-data MCP responses for one full UK address.",
+  "type": "object",
+  "required": ["out_dir", "filename_stem", "address", "postcode", "generated", "valuation", "area", "demand_trend"],
+  "properties": {
+    "out_dir":        { "type": "string", "description": "Absolute path to the output directory (created if missing)." },
+    "filename_stem":  { "type": "string", "description": "PDF filename stem; .pdf appended by the renderer." },
+    "address":        { "type": "string", "description": "Full UK address as the operator gave it." },
+    "postcode":       { "type": "string", "description": "Postcode derived from the address, e.g. 'CM23 2UJ'." },
+    "generated":      { "type": "string", "description": "Human date, e.g. '19 May 2026'." },
+    "valuation": {
+      "type": "object",
+      "required": ["avg_asking", "asking_psf", "avg_sold", "sold_psf", "sold_comps", "asking_comps"],
+      "properties": {
+        "avg_asking":   { "type": "integer", "description": "Mean asking £ (from property-data-prices)." },
+        "asking_psf":   { "type": "integer", "description": "Asking £/sqft (from property-data-prices-per-sqf)." },
+        "avg_sold":     { "type": "integer", "description": "Mean sold £ (from property-data-sold-prices)." },
+        "sold_psf":     { "type": "integer", "description": "Sold £/sqft (from property-data-sold-prices-per-sqf)." },
+        "sold_range":   { "type": "array", "items": { "type": "integer" }, "minItems": 2, "maxItems": 2, "description": "Optional 70pc range [low, high]." },
+        "sold_comps": {
+          "type": "array",
+          "description": "Nearest sold transactions (≤ 6 rows in the table).",
+          "items": {
+            "type": "object",
+            "required": ["date", "address", "type", "price"],
+            "properties": {
+              "date":     { "type": "string" },
+              "address":  { "type": "string" },
+              "type":     { "type": "string" },
+              "price":    { "type": "integer" }
+            }
+          }
+        },
+        "asking_comps": {
+          "type": "array",
+          "description": "Live asking comps (≤ 4 tiles).",
+          "items": {
+            "type": "object",
+            "required": ["address", "price"],
+            "properties": {
+              "address":  { "type": "string" },
+              "price":    { "type": "integer" },
+              "beds":     { "type": ["integer", "null"] },
+              "type":     { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    },
+    "area": {
+      "type": "object",
+      "required": ["crime_rating", "flood_risk", "council_tax_band_d", "population", "crime_breakdown", "council_tax_bands", "headline"],
+      "properties": {
+        "crime_rating":     { "type": "string", "description": "e.g. 'Below average'." },
+        "flood_risk":       { "type": "string", "description": "e.g. 'Very low'." },
+        "council_tax_band_d": { "type": "integer", "description": "Annual £ at band D." },
+        "population":       { "type": "integer", "description": "Local area population." },
+        "crime_breakdown": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["category", "count"],
+            "properties": {
+              "category": { "type": "string" },
+              "count":    { "type": "integer" }
+            }
+          }
+        },
+        "council_tax_bands": {
+          "type": "array",
+          "description": "Band → annual £ rows.",
+          "items": {
+            "type": "object",
+            "required": ["band", "amount"],
+            "properties": {
+              "band":   { "type": "string" },
+              "amount": { "type": "integer" }
+            }
+          }
+        },
+        "headline": { "type": "string", "description": "One-sentence area read." }
+      }
+    },
+    "demand_trend": {
+      "type": "object",
+      "required": ["demand_rating", "dom", "turnover_pct", "for_sale", "growth_series", "growth_psf_series", "rental", "type_dist"],
+      "properties": {
+        "demand_rating": { "type": "string", "description": "e.g. 'Balanced market'." },
+        "dom":           { "type": "integer", "description": "Days on market." },
+        "turnover_pct":  { "type": "integer", "description": "Turnover percent per month." },
+        "for_sale":      { "type": "integer", "description": "Current for-sale count." },
+        "growth_series": {
+          "type": "array",
+          "description": "7-year £ series, oldest first.",
+          "items": {
+            "type": "object",
+            "required": ["label", "price"],
+            "properties": {
+              "label": { "type": "string" },
+              "price": { "type": "integer" }
+            }
+          }
+        },
+        "growth_psf_series": {
+          "type": "array",
+          "description": "7-year £/sqft series, oldest first.",
+          "items": {
+            "type": "object",
+            "required": ["label", "psf"],
+            "properties": {
+              "label": { "type": "string" },
+              "psf":   { "type": "integer" }
+            }
+          }
+        },
+        "rental": {
+          "type": "object",
+          "required": ["demand_rating", "dom", "turnover_pct", "for_rent"],
+          "properties": {
+            "demand_rating": { "type": "string" },
+            "dom":           { "type": "integer" },
+            "turnover_pct":  { "type": "integer" },
+            "for_rent":      { "type": "integer" }
+          }
+        },
+        "type_dist": {
+          "type": "array",
+          "description": "Property-type mix doughnut rows.",
+          "items": {
+            "type": "object",
+            "required": ["name", "pct"],
+            "properties": {
+              "name": { "type": "string" },
+              "pct":  { "type": "number" }
+            }
+          }
+        }
+      }
+    }
+  }
+}