traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/skills.py

@@ -0,0 +1,131 @@
+"""Skills: reusable, on-demand instructions for recurring kinds of work.
+
+A skill is a folder with a ``SKILL.md`` file that starts with YAML front matter
+(``name`` and ``description``) followed by Markdown instructions, plus any
+supporting files (checklists, scripts, templates). Skills are found, in order of
+precedence (later wins on a name clash):
+
+1. built in, shipped with Traceforge (``traceforge/skill_library/``),
+2. the user's, in ``~/.config/traceforge/skills/<name>/SKILL.md``,
+3. the project's, in ``.traceforge/skills/<name>/SKILL.md``.
+
+Only names and descriptions go into the system prompt. The agent loads the full
+instructions with the ``load_skill`` tool when a task matches (progressive
+disclosure), so unused skills cost almost nothing.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+import yaml
+
+from traceforge.config import config_home
+
+MAX_SKILLS = 64
+MAX_SKILL_BYTES = 64 * 1024
+MAX_DESCRIPTION = 500
+NAME = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+FRONT_MATTER = re.compile(r"^---\r?\n(.*?)\r?\n---\r?\n?", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    path: Path  # the SKILL.md file
+    source: str  # built-in | user | project
+
+    @property
+    def folder(self) -> Path:
+        return self.path.parent
+
+    def body(self) -> str:
+        text = self.path.read_text(encoding="utf-8")
+        match = FRONT_MATTER.match(text)
+        return text[match.end() :].strip() if match else text.strip()
+
+    def files(self) -> list[str]:
+        return sorted(
+            p.relative_to(self.folder).as_posix()
+            for p in self.folder.rglob("*")
+            if p.is_file() and p.name != "SKILL.md" and "__pycache__" not in p.parts
+        )[:100]
+
+
+def parse_skill(path: Path, source: str) -> tuple[Skill | None, str | None]:
+    """Read one SKILL.md; returns (skill, None) or (None, problem)."""
+    folder = path.parent.name
+    try:
+        if path.stat().st_size > MAX_SKILL_BYTES:
+            return None, f"{folder}: SKILL.md is larger than {MAX_SKILL_BYTES} bytes"
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return None, f"{folder}: {exc}"
+    match = FRONT_MATTER.match(text)
+    if not match:
+        return None, f"{folder}: SKILL.md has no YAML front matter"
+    try:
+        meta = yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError:
+        return None, f"{folder}: invalid YAML front matter"
+    if not isinstance(meta, dict):
+        return None, f"{folder}: invalid front matter"
+    name = str(meta.get("name") or folder).strip().lower()
+    description = " ".join(str(meta.get("description") or "").split())[:MAX_DESCRIPTION]
+    if not NAME.match(name):
+        return None, f"{folder}: invalid skill name {name!r}"
+    if not description:
+        return None, f"{folder}: missing description"
+    return Skill(name, description, path, source), None
+
+
+def _roots(workspace: Path | None) -> list[tuple[Path, str]]:
+    roots: list[tuple[Path, str]] = []
+    try:
+        builtin = Path(str(resources.files("traceforge").joinpath("skill_library")))
+        roots.append((builtin, "built-in"))
+    except (ModuleNotFoundError, TypeError):  # pragma: no cover
+        pass
+    roots.append((config_home() / "skills", "user"))
+    if workspace is not None:
+        roots.append((Path(workspace) / ".traceforge" / "skills", "project"))
+    return roots
+
+
+def discover(workspace: Path | None) -> tuple[dict[str, Skill], list[str]]:
+    skills: dict[str, Skill] = {}
+    problems: list[str] = []
+    for root, source in _roots(workspace):
+        if not root.is_dir():
+            continue
+        for folder in sorted(root.iterdir()):
+            file = folder / "SKILL.md"
+            if not folder.is_dir() or not file.is_file():
+                continue
+            skill, problem = parse_skill(file, source)
+            if problem:
+                problems.append(f"{source} skill {problem}")
+            elif skill is not None:
+                skills[skill.name] = skill
+            if len(skills) >= MAX_SKILLS:
+                break
+    return skills, problems
+
+
+def prompt_section(skills: dict[str, Skill]) -> str:
+    if not skills:
+        return ""
+    lines = [
+        "# Skills",
+        "",
+        "These skills hold tested instructions for recurring tasks. When a request matches one, "
+        "call `load_skill` with its name before you start, then follow it.",
+        "",
+    ]
+    for skill in sorted(skills.values(), key=lambda s: s.name):
+        lines.append(f"- {skill.name} ({skill.source}): {skill.description}")
+    return "\n".join(lines)

traceforge/thermal.py

@@ -0,0 +1,557 @@
+"""First-order thermal analysis of a KiCad design.
+
+Per part: estimated dissipation, copper area around it (pours on every layer, tracks of the heat-sinking
+nets, thermal vias), a junction temperature estimate Tj = Ta + P * theta_JA and mitigation advice.
+
+This is a screening model, not a simulation. See ``LIMITS``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from traceforge import sexpr
+from traceforge.kicad.pcb import Board, Footprint
+from traceforge.sexpr import find, find_all, num, value
+from traceforge.validate import circuits
+from traceforge.validate.netmodel import DesignModel, Part
+
+LIMITS = (
+    "Screening estimate only: steady-state, single part, still air, no neighbour heating or enclosure. "
+    "theta_JA comes from the datasheet when given, otherwise from a typical per-package table (JEDEC "
+    "minimum-pad value) scaled by copper area with an empirical power law that is only credible within "
+    "about +/-40 percent. Copper area counts pours, tracks and pads of the heat-sinking nets inside a square "
+    "window around the part, summed over layers; it ignores pour shape, thermal reliefs and via count beyond "
+    "a simple tally. Load currents of ICs are not guessed: give them with 'loads' or 'rail_current_ma', "
+    "otherwise only the loads that can be derived from the schematic (resistor and LED chains) are counted. "
+    "Linear-regulator dissipation excludes quiescent current unless 'iq_ma' is given. Verify with the datasheet "
+    "thermal curves and a measurement before relying on it."
+)
+
+
+# Typical junction-to-ambient thermal resistance (K/W) on a minimum-copper JEDEC board, the copper
+# area (mm2) that value assumes, and whether the package spreads heat into copper through a tab or pad.
+@dataclass(frozen=True)
+class PackageThermal:
+    pattern: str
+    theta_ja: float
+    ref_area_mm2: float
+    spreads: bool
+
+
+PACKAGE_TABLE: tuple[PackageThermal, ...] = (
+    PackageThermal(r"SOT-?223", 90.0, 100.0, True),
+    PackageThermal(r"TO-?263|D2PAK", 60.0, 150.0, True),
+    PackageThermal(r"TO-?252|DPAK", 80.0, 100.0, True),
+    PackageThermal(r"TO-?220", 50.0, 0.0, False),
+    PackageThermal(r"SOT-?89", 150.0, 60.0, True),
+    PackageThermal(r"SOT-?23", 220.0, 20.0, False),
+    PackageThermal(r"SC-?70|SOT-?323|SOT-?363", 300.0, 10.0, False),
+    PackageThermal(r"HSOP|SOIC.*EP|SO.*PowerPAD|ESOP", 50.0, 150.0, True),
+    PackageThermal(r"SOIC-?16|SO-?16", 100.0, 0.0, False),
+    PackageThermal(r"SOIC|SOP-?8|SO-?8", 130.0, 0.0, False),
+    PackageThermal(r"TSSOP|MSOP|SSOP", 110.0, 0.0, False),
+    PackageThermal(r"QFN-?(?:16|20|24)|DFN|WSON|VSON|LGA", 55.0, 100.0, True),
+    PackageThermal(r"QFN|VQFN|WQFN", 35.0, 150.0, True),
+    PackageThermal(r"LQFP|TQFP|QFP", 55.0, 0.0, False),
+    PackageThermal(r"BGA|CSP", 45.0, 0.0, False),
+    PackageThermal(r"DIP|PDIP", 100.0, 0.0, False),
+    PackageThermal(r"SMA|SMB|SMC|SOD-?123|SOD-?323", 100.0, 40.0, True),
+    PackageThermal(r"2512", 70.0, 60.0, True),
+    PackageThermal(r"1206", 100.0, 20.0, True),
+    PackageThermal(r"0805", 180.0, 10.0, True),
+    PackageThermal(r"0603", 250.0, 6.0, True),
+    PackageThermal(r"0402", 350.0, 3.0, True),
+)
+DEFAULT_THETA = PackageThermal("", 120.0, 0.0, False)
+
+_THETA_RE = re.compile(
+    r"(?:R?\s*(?:θ|Θ|theta|Theta)\s*_?\s*\(?\s*(?:JA|J-A)\)?|junction[- ]to[- ]ambient)[^0-9\n]{0,60}"
+    r"(\d{2,3}(?:\.\d+)?)\s*(?:°\s*C\s*/\s*W|K\s*/\s*W|C\s*/\s*W)",
+    re.I,
+)
+_SWITCHER = re.compile(
+    r"TPS5|TPS6|LM2596|LM2576|MP1584|MP2307|MP2315|AP63|AP62|XL4015|XL1509|MT3608|LMR\d|RT6\d|SY8\d|"
+    r"TLV62|TLV61|TPS54|BUCK|BOOST|SWITCHER",
+    re.I,
+)
+_MOSFET = re.compile(r"MOSFET|^Q$|AO3400|AO3401|IRLML|SI23|DMN|DMP|IRF|2N7002|BSS138", re.I)
+
+
+def extract_theta_ja(pages: list[str]) -> tuple[float, int] | None:
+    """(theta_JA in K/W, page number) from datasheet page texts, or None."""
+    for number, text in enumerate(pages, start=1):
+        match = _THETA_RE.search(text)
+        if match:
+            return float(match.group(1)), number
+    return None
+
+
+def package_thermal(footprint: str) -> PackageThermal:
+    for entry in PACKAGE_TABLE:
+        if re.search(entry.pattern, footprint, re.I):
+            return entry
+    return DEFAULT_THETA
+
+
+# ----------------------------------------------------------------------------- copper
+
+
+def _clip_area(points: list[tuple[float, float]], box: tuple[float, float, float, float]) -> float:
+    """Area of a polygon clipped to an axis-aligned box (Sutherland-Hodgman)."""
+    x0, y0, x1, y1 = box
+
+    def clip(poly, inside, cross):
+        out = []
+        for i, cur in enumerate(poly):
+            prev = poly[i - 1]
+            if inside(cur):
+                if not inside(prev):
+                    out.append(cross(prev, cur))
+                out.append(cur)
+            elif inside(prev):
+                out.append(cross(prev, cur))
+        return out
+
+    def at_x(x):
+        return lambda a, b: (x, a[1] + (b[1] - a[1]) * (x - a[0]) / (b[0] - a[0]))
+
+    def at_y(y):
+        return lambda a, b: (a[0] + (b[0] - a[0]) * (y - a[1]) / (b[1] - a[1]), y)
+
+    poly = points
+    for inside, cross in (
+        (lambda p: p[0] >= x0, at_x(x0)),
+        (lambda p: p[0] <= x1, at_x(x1)),
+        (lambda p: p[1] >= y0, at_y(y0)),
+        (lambda p: p[1] <= y1, at_y(y1)),
+    ):
+        if not poly:
+            return 0.0
+        poly = clip(poly, inside, cross)
+    if len(poly) < 3:
+        return 0.0
+    return (
+        abs(sum(a[0] * b[1] - b[0] * a[1] for a, b in zip(poly, poly[1:] + poly[:1], strict=True)))
+        / 2
+    )
+
+
+def filled_polygons(path: Path) -> list[tuple[str, str, list[tuple[float, float]]]]:
+    """(net, layer, outline points) of every filled zone polygon in a board file."""
+    root = sexpr.parse(path.read_text(encoding="utf-8"))
+    found = []
+    for zone in find_all(root, "zone"):
+        net = str(value(zone, "net_name", ""))
+        for poly in find_all(zone, "filled_polygon"):
+            layer = str(value(poly, "layer", ""))
+            pts = find(poly, "pts")
+            if pts is None:
+                continue
+            points = [
+                (num(p[1]), num(p[2])) for p in pts[1:] if isinstance(p, list) and len(p) >= 3
+            ]
+            if len(points) >= 3:
+                found.append((net, layer, points))
+    return found
+
+
+@dataclass
+class Copper:
+    nets: list[str] = field(default_factory=list)
+    by_layer_mm2: dict[str, float] = field(default_factory=dict)
+    total_mm2: float = 0.0
+    thermal_vias: int = 0
+    window_mm: float = 0.0
+
+
+def copper_around(
+    board: Board,
+    footprint: Footprint,
+    polygons: list[tuple[str, str, list[tuple[float, float]]]],
+    *,
+    window_mm: float = 10.0,
+) -> Copper:
+    """Copper of the part's heat-sinking nets inside a window centred on the part.
+
+    Heat-sinking nets are those of pads at least half as large as the largest pad (tab or exposed pad)."""
+    area = lambda p: p.width * p.height  # noqa: E731
+    biggest = max((area(p) for p in footprint.pads), default=0.0)
+    nets = sorted({p.net for p in footprint.pads if p.net and area(p) >= 0.5 * biggest})
+    box = (
+        footprint.x - window_mm,
+        footprint.y - window_mm,
+        footprint.x + window_mm,
+        footprint.y + window_mm,
+    )
+    by_layer: dict[str, float] = {}
+    for net, layer, points in polygons:
+        if net in nets:
+            by_layer[layer] = by_layer.get(layer, 0.0) + _clip_area(points, box)
+    for track in board.tracks:
+        if track.net in nets and (box[0] <= track.x1 <= box[2] and box[1] <= track.y1 <= box[3]):
+            by_layer[track.layer] = by_layer.get(track.layer, 0.0) + track.length * track.width
+    for pad in footprint.pads:
+        if pad.net in nets:
+            for layer in pad.layers:
+                if layer.endswith(".Cu"):
+                    by_layer[layer] = by_layer.get(layer, 0.0) + area(pad)
+    vias = sum(
+        1
+        for v in board.vias
+        if v.net in nets
+        and abs(v.x - footprint.x) <= window_mm / 2
+        and abs(v.y - footprint.y) <= window_mm / 2
+    )
+    return Copper(
+        nets,
+        {k: round(v, 1) for k, v in by_layer.items()},
+        round(sum(by_layer.values()), 1),
+        vias,
+        window_mm,
+    )
+
+
+def effective_theta(entry: PackageThermal, copper_mm2: float | None) -> tuple[float, str]:
+    """theta_JA after scaling the table value to the actual copper area (heat-spreading packages)."""
+    if not entry.spreads or entry.ref_area_mm2 <= 0 or not copper_mm2:
+        return entry.theta_ja, "package table (no copper scaling)"
+    ratio = max(0.25, min(8.0, copper_mm2 / entry.ref_area_mm2))
+    factor = max(0.45, min(1.6, ratio**-0.3))
+    return round(entry.theta_ja * factor, 1), f"package table scaled by copper area (x{factor:.2f})"
+
+
+# ------------------------------------------------------------------------- dissipation
+
+
+@dataclass
+class PartThermal:
+    ref: str
+    kind: str
+    power_mw: float
+    basis: str
+    footprint: str = ""
+    theta_ja: float | None = None
+    theta_source: str = ""
+    copper: Copper | None = None
+    tj_c: float | None = None
+    tj_max_c: float = 125.0
+    margin_c: float | None = None
+    severity: str = ""
+    advice: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        data = {
+            "ref": self.ref,
+            "kind": self.kind,
+            "power_mw": round(self.power_mw, 2),
+            "basis": self.basis,
+            "footprint": self.footprint,
+            "theta_ja_k_per_w": self.theta_ja,
+            "theta_source": self.theta_source,
+            "junction_c": None if self.tj_c is None else round(self.tj_c, 1),
+            "tj_max_c": self.tj_max_c,
+            "margin_c": None if self.margin_c is None else round(self.margin_c, 1),
+            "severity": self.severity,
+            "advice": self.advice,
+        }
+        if self.copper is not None:
+            data["copper"] = {
+                "nets": self.copper.nets,
+                "total_mm2": self.copper.total_mm2,
+                "by_layer_mm2": self.copper.by_layer_mm2,
+                "thermal_vias": self.copper.thermal_vias,
+                "window_mm": self.copper.window_mm,
+            }
+        return data
+
+
+def linear_regulator_mw(vin: float, vout: float, iout_a: float, iq_a: float = 0.0) -> float:
+    return ((vin - vout) * iout_a + vin * iq_a) * 1000.0
+
+
+def switching_regulator_mw(vout: float, iout_a: float, efficiency: float) -> float:
+    return vout * iout_a * (1.0 / efficiency - 1.0) * 1000.0
+
+
+def resistor_mw(ohms: float, amps: float | None = None, volts: float | None = None) -> float:
+    if amps is not None:
+        return amps * amps * ohms * 1000.0
+    return (volts or 0.0) ** 2 / ohms * 1000.0
+
+
+def mosfet_mw(rds_on_ohm: float, amps: float) -> float:
+    return amps * amps * rds_on_ohm * 1000.0
+
+
+def _pin_nets(model: DesignModel, part: Part) -> list[str]:
+    return sorted(set(model.part_nets(part.ref).values()))
+
+
+def rail_currents(
+    model: DesignModel,
+    volts: dict[str, float],
+    overrides_ma: dict[str, float],
+    loads_ma: dict[str, float],
+) -> tuple[dict[str, float], list[str]]:
+    """Current (A) drawn from each rail by the loads we can derive, plus a list of unaccounted consumers."""
+    totals: dict[str, float] = {}
+    notes: list[str] = []
+    for net, ma in overrides_ma.items():
+        totals[net] = ma / 1000.0
+    for part in model.parts.values():
+        if part.dnp:
+            continue
+        nets = _pin_nets(model, part)
+        if part.ref in loads_ma:
+            for net in nets:
+                if volts.get(net, 0) > 0.5 and net not in overrides_ma:
+                    totals[net] = totals.get(net, 0.0) + loads_ma[part.ref] / 1000.0
+            continue
+        if part.prefix == "R" and len(nets) == 2:
+            high, low = sorted(nets, key=lambda n: -volts.get(n, -99))
+            if volts.get(low) == 0.0 and volts.get(high, 0) > 0 and high not in overrides_ma:
+                ohms = circuits.parse_resistance(part.value)
+                if ohms:
+                    totals[high] = totals.get(high, 0.0) + volts[high] / ohms
+    for part in model.parts.values():
+        if part.dnp or part.prefix != "R" or part.ref in loads_ma:
+            continue
+        # LED chain: rail -> R -> LED -> ground (or the reverse order)
+        nets = _pin_nets(model, part)
+        ohms = circuits.parse_resistance(part.value)
+        if not ohms or len(nets) != 2:
+            continue
+        for rail, mid in (nets, nets[::-1]):
+            if volts.get(rail, 0) <= 0 or rail in overrides_ma:
+                continue
+            leds = [
+                model.parts[r]
+                for r in model.refs_on(mid)
+                if r in model.parts and circuits.is_led(model.parts[r])
+            ]
+            if len(leds) == 1:
+                led = leds[0]
+                vf = circuits.led_color(led).vf_typ
+                current = max(0.0, (volts[rail] - vf) / ohms)
+                loads_ma.setdefault(f"__led_{part.ref}", current * 1000.0)
+                totals[rail] = totals.get(rail, 0.0) + current
+                break
+    for part in model.parts.values():
+        if circuits.is_ic(part) and not circuits.is_regulator(part) and part.ref not in loads_ma:
+            notes.append(part.ref)
+    return totals, notes
+
+
+def analyse(
+    model: DesignModel,
+    board: Board,
+    *,
+    ambient_c: float = 25.0,
+    loads_ma: dict[str, float] | None = None,
+    rail_current_ma: dict[str, float] | None = None,
+    power_mw: dict[str, float] | None = None,
+    theta_ja: dict[str, float] | None = None,
+    iq_ma: dict[str, float] | None = None,
+    rds_on_mohm: dict[str, float] | None = None,
+    efficiency: float = 0.85,
+    window_mm: float = 10.0,
+    tj_max_c: float = 125.0,
+    min_report_mw: float = 20.0,
+    datasheet_theta: dict[str, tuple[float, str]] | None = None,
+) -> dict[str, Any]:
+    loads_ma = dict(loads_ma or {})
+    volts = circuits.infer_voltages(model)
+    currents, unaccounted = rail_currents(model, volts, dict(rail_current_ma or {}), loads_ma)
+    polygons = filled_polygons(board.path)
+    results: list[PartThermal] = []
+    assumptions: list[str] = []
+
+    def add(part: Part, kind: str, mw: float, basis: str) -> None:
+        fp = model.footprint(part.ref)
+        entry = package_thermal(part.footprint or (fp.lib_id if fp else ""))
+        item = PartThermal(part.ref, kind, mw, basis, part.footprint, tj_max_c=tj_max_c)
+        copper = copper_around(board, fp, polygons, window_mm=window_mm) if fp else None
+        item.copper = copper
+        if theta_ja and part.ref in theta_ja:
+            item.theta_ja, item.theta_source = theta_ja[part.ref], "user value"
+        elif datasheet_theta and part.ref in datasheet_theta:
+            value_, page = datasheet_theta[part.ref]
+            item.theta_ja, item.theta_source = value_, f"datasheet page {page}"
+        else:
+            item.theta_ja, item.theta_source = effective_theta(
+                entry, copper.total_mm2 if copper else None
+            )
+        item.tj_c = ambient_c + mw / 1000.0 * item.theta_ja
+        item.margin_c = tj_max_c - item.tj_c
+        item.severity = "P1" if item.margin_c < 0 else "P2" if item.margin_c < 25 else "ok"
+        item.advice = mitigation(item, entry)
+        results.append(item)
+
+    for part in model.parts.values():
+        if part.dnp:
+            continue
+        ref = part.ref
+        if power_mw and ref in power_mw:
+            add(part, "user", power_mw[ref], "power given by user")
+        elif circuits.is_regulator(part):
+            vout = circuits.regulator_output(part)
+            ins, outs = circuits.regulator_pins(part)
+            in_net = next((model.net_of(ref, p) for p in ins if model.net_of(ref, p)), None)
+            out_net = next((model.net_of(ref, p) for p in outs if model.net_of(ref, p)), None)
+            vin = volts.get(in_net or "")
+            vout = vout if vout is not None else volts.get(out_net or "")
+            iout = currents.get(out_net or "")
+            if ref in loads_ma and out_net is None:
+                iout = loads_ma[ref] / 1000.0
+            if vin is None or vout is None or iout is None:
+                assumptions.append(
+                    f"{ref}: regulator vin/vout/load unknown; give rail_current_ma or power_mw"
+                )
+                continue
+            iq = (iq_ma or {}).get(ref, 0.0) / 1000.0
+            if _SWITCHER.search(part.text):
+                eff = efficiency
+                add(
+                    part,
+                    "switching regulator",
+                    switching_regulator_mw(vout, iout, eff),
+                    f"Pout*(1/eta-1): {vout:g} V x {iout * 1000:.1f} mA, eta {eff:g} (assumed)",
+                )
+            else:
+                add(
+                    part,
+                    "linear regulator",
+                    linear_regulator_mw(vin, vout, iout, iq),
+                    f"(Vin-Vout)*Iout: ({vin:g}-{vout:g}) V x {iout * 1000:.1f} mA"
+                    + (f" + Vin*Iq {iq * 1000:g} mA" if iq else ""),
+                )
+        elif circuits.is_led(part):
+            res = [
+                r
+                for r in model.parts.values()
+                if r.prefix == "R" and set(_pin_nets(model, r)) & set(_pin_nets(model, part))
+            ]
+            current = loads_ma.get(ref)
+            vf = circuits.led_color(part).vf_typ
+            if current is None:
+                for r in res:
+                    ohms = circuits.parse_resistance(r.value)
+                    others = [n for n in _pin_nets(model, r) if n not in _pin_nets(model, part)]
+                    if ohms and others and volts.get(others[0], 0) > vf:
+                        current = (volts[others[0]] - vf) / ohms * 1000.0
+                        break
+            if current:
+                add(
+                    part,
+                    "LED",
+                    vf * current,
+                    f"Vf*If: {vf:g} V x {current:.1f} mA (Vf typical for colour)",
+                )
+        elif part.prefix == "R":
+            ohms = circuits.parse_resistance(part.value)
+            nets = _pin_nets(model, part)
+            if not ohms or len(nets) != 2:
+                continue
+            amps = (loads_ma.get(ref) or 0.0) / 1000.0 or None
+            va, vb = volts.get(nets[0]), volts.get(nets[1])
+            if amps is not None:
+                add(
+                    part,
+                    "resistor",
+                    resistor_mw(ohms, amps=amps),
+                    f"I^2*R: {amps * 1000:g} mA, {ohms:g} ohm",
+                )
+            elif va is not None and vb is not None and va != vb:
+                add(
+                    part,
+                    "resistor",
+                    resistor_mw(ohms, volts=abs(va - vb)),
+                    f"V^2/R: {abs(va - vb):g} V across {ohms:g} ohm",
+                )
+            else:
+                led_current = _led_chain_current(model, volts, part, ohms)
+                if led_current:
+                    add(
+                        part,
+                        "resistor",
+                        resistor_mw(ohms, amps=led_current),
+                        f"I^2*R: {led_current * 1000:.1f} mA LED chain, {ohms:g} ohm",
+                    )
+        elif _MOSFET.search(part.text) or (part.prefix == "Q" and "MOS" in part.text):
+            rds = (rds_on_mohm or {}).get(ref)
+            amps = (loads_ma.get(ref) or 0.0) / 1000.0
+            if rds and amps:
+                add(
+                    part,
+                    "MOSFET",
+                    mosfet_mw(rds / 1000.0, amps),
+                    f"I^2*Rds(on): {amps * 1000:g} mA, {rds:g} mohm",
+                )
+            else:
+                assumptions.append(
+                    f"{ref}: MOSFET needs rds_on_mohm and loads (mA) to estimate dissipation"
+                )
+    results = [r for r in results if r.power_mw >= min_report_mw or r.severity != "ok"]
+    results.sort(key=lambda r: -(r.tj_c or 0))
+    hotspots = [r.ref for r in results if r.severity != "ok"]
+    if unaccounted:
+        assumptions.append(
+            "IC supply currents not counted unless given in 'loads': " + ", ".join(unaccounted[:12])
+        )
+    return {
+        "ambient_c": ambient_c,
+        "parts": [r.to_dict() for r in results],
+        "hotspots": hotspots,
+        "rail_current_ma": {n: round(a * 1000, 2) for n, a in sorted(currents.items())},
+        "assumptions": assumptions,
+        "limits": LIMITS,
+    }
+
+
+def _led_chain_current(
+    model: DesignModel, volts: dict[str, float], res: Part, ohms: float
+) -> float | None:
+    nets = _pin_nets(model, res)
+    for rail, mid in (nets, nets[::-1]):
+        if volts.get(rail, 0) <= 0:
+            continue
+        leds = [
+            model.parts[r]
+            for r in model.refs_on(mid)
+            if r in model.parts and circuits.is_led(model.parts[r])
+        ]
+        if len(leds) == 1:
+            return max(0.0, (volts[rail] - circuits.led_color(leds[0]).vf_typ) / ohms)
+    return None
+
+
+def mitigation(item: PartThermal, entry: PackageThermal) -> list[str]:
+    if item.severity == "ok":
+        return []
+    advice = []
+    copper = item.copper.total_mm2 if item.copper else 0.0
+    if entry.spreads:
+        target = max(entry.ref_area_mm2 * 4, copper * 2, 400)
+        advice.append(
+            f"Increase copper on the heat-sinking pad/tab net ({', '.join(item.copper.nets) if item.copper else '?'}): "
+            f"now about {copper:.0f} mm2 within {item.copper.window_mm:g} mm, aim for 400+ mm2 (>= {target:.0f})."
+        )
+        if item.copper is None or item.copper.thermal_vias < 4:
+            advice.append(
+                "Add 4 to 9 thermal vias (0.3 mm drill) under or beside the pad to an inner/bottom pour."
+            )
+    else:
+        advice.append(
+            "This package has little copper coupling: move the part away from other heat sources and pour copper on its power pins."
+        )
+    advice.append(
+        f"Reduce dissipation ({item.power_mw:.0f} mW): lower the input-output drop (pre-regulator or buck), "
+        "spread the load over parts, or use a switching stage."
+        if item.kind == "linear regulator"
+        else f"Reduce dissipation ({item.power_mw:.0f} mW) or choose a package with a lower theta_JA."
+    )
+    return advice