traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/tools/models3d_tools.py

@@ -0,0 +1,141 @@
+"""Agent tools for 3D models: check, assign and render (see traceforge.kicad.models3d)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from traceforge.kicad import models3d
+from traceforge.tools.base import Tool, ToolContext, ToolError, ToolKind, ToolOutput
+from traceforge.tools.files import _image_output
+from traceforge.tools.kicad_tools import _out_dir, _pcb_path
+
+_PCB = {"type": "string", "description": "board path (default: the project's)"}
+_VEC = {"type": "array", "items": {"type": "number"}, "minItems": 3, "maxItems": 3}
+
+
+def _model_file(raw: str, ctx: ToolContext) -> Path:
+    """A model inside the workspace, or one inside an installed KiCad 3D library."""
+    candidate = Path(raw).expanduser()
+    if candidate.is_absolute() and candidate.is_file():
+        resolved = candidate.resolve()
+        for base in models3d.model_dirs():
+            if base.resolve() in resolved.parents:
+                return resolved
+    return ctx.resolve(raw, must_exist=True)
+
+
+def models_check(args: dict[str, Any], ctx: ToolContext) -> dict:
+    pcb = _pcb_path(args, ctx)
+    rows = models3d.inventory(pcb)
+    problems = [r.to_dict() for r in rows if r.status != "resolved"]
+    findings = models3d.check_models(pcb)
+    return {
+        "summary": models3d.summary(rows),
+        "model_libraries": [str(d) for d in models3d.model_dirs()],
+        "problems": problems,
+        "findings": [f.to_dict() for f in findings],
+        "note": "proposals carry a confidence; only 0.90 and above are exact name matches",
+    }
+
+
+def models_assign(args: dict[str, Any], ctx: ToolContext) -> dict:
+    pcb = _pcb_path(args, ctx, for_write=True)
+    overwrite = bool(args.get("overwrite"))
+    try:
+        if args.get("auto"):
+            return {
+                "results": models3d.assign_proposed(pcb, float(args.get("min_confidence") or 0.9))
+            }
+        ref = args.get("ref")
+        if not ref:
+            raise ToolError("pass 'ref' (with 'model' or 'generate') or auto=true")
+        if args.get("generate"):
+            return models3d.assign_generic(pcb, ref, args["generate"], overwrite=overwrite)
+        if not args.get("model"):
+            raise ToolError("pass 'model' (a .step/.wrl file), 'generate', or auto=true")
+        vec = lambda key, default: tuple(float(v) for v in args.get(key) or default)  # noqa: E731
+        return models3d.assign_model(
+            pcb,
+            ref,
+            _model_file(args["model"], ctx),
+            vec("offset", (0, 0, 0)),
+            vec("scale", (1, 1, 1)),
+            vec("rotate", (0, 0, 0)),
+            overwrite=overwrite,
+        )
+    except models3d.ModelError as exc:
+        raise ToolError(str(exc)) from exc
+
+
+def render_3d(args: dict[str, Any], ctx: ToolContext) -> ToolOutput:
+    pcb = _pcb_path(args, ctx)
+    side = args.get("side") or "top"
+    out = _out_dir(ctx, "render") / f"{pcb.stem}-{side}.png"
+    try:
+        models3d.render_3d(
+            pcb,
+            out,
+            side,
+            width=int(args.get("width") or 1600),
+            height=int(args.get("height") or 900),
+            quality=args.get("quality") or "basic",
+            perspective=bool(args.get("perspective")),
+        )
+    except models3d.RenderError as exc:
+        raise ToolError(str(exc)) from exc
+    return _image_output(out, ctx)
+
+
+MODELS3D_TOOLS = [
+    Tool(
+        "kicad_models_check",
+        "Check every footprint's 3D model: resolved path, missing file, or no model. Lists "
+        "library proposals with a confidence for footprints that need one. Read-only.",
+        {"type": "object", "properties": {"pcb": _PCB}},
+        models_check,
+    ),
+    Tool(
+        "kicad_models_assign",
+        "Write a (model ...) entry into a board footprint. Give ref + model (a .step/.wrl in the "
+        "workspace or KiCad's 3D library; files outside the project are copied to 3dmodels/), or "
+        "ref + generate ('step'|'wrl') for a labelled generic placeholder sized from the "
+        "footprint, or auto=true to assign exact library matches (min_confidence, default 0.9). "
+        "Never replaces an existing model unless overwrite=true.",
+        {
+            "type": "object",
+            "properties": {
+                "pcb": _PCB,
+                "ref": {"type": "string"},
+                "model": {"type": "string"},
+                "generate": {"type": "string", "enum": ["step", "wrl"]},
+                "auto": {"type": "boolean"},
+                "min_confidence": {"type": "number"},
+                "offset": _VEC,
+                "scale": _VEC,
+                "rotate": _VEC,
+                "overwrite": {"type": "boolean"},
+            },
+        },
+        models_assign,
+        ToolKind.WRITE,
+        "pcb",
+    ),
+    Tool(
+        "kicad_render_3d",
+        "Render the board in 3D (top or bottom) with `kicad-cli pcb render` and show the image. "
+        "Needs KiCad 8 or later; on KiCad 7 it reports that plainly.",
+        {
+            "type": "object",
+            "properties": {
+                "pcb": _PCB,
+                "side": {"type": "string", "enum": ["top", "bottom"]},
+                "width": {"type": "integer"},
+                "height": {"type": "integer"},
+                "quality": {"type": "string", "enum": ["basic", "high"]},
+                "perspective": {"type": "boolean"},
+            },
+        },
+        render_3d,
+    ),
+]

traceforge/tools/parts_tools.py

@@ -0,0 +1,473 @@
+"""Agent tools for live part data, datasheets and the web. All read-only."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from traceforge.parts import Offline, ProviderError, default_catalog, is_lcsc_code
+from traceforge.tools.base import Tool, ToolContext, ToolError, ToolKind
+
+
+def _offline_error(exc: Exception) -> ToolError:
+    return ToolError(
+        f"not verified: offline or unreachable ({exc}). Do not guess part numbers; say they are "
+        "unverified."
+    )
+
+
+def part_lookup(args: dict[str, Any], ctx: ToolContext) -> dict:
+    catalog = default_catalog()
+    queries = [q for q in [args.get("part"), *(args.get("parts") or [])] if q and str(q).strip()]
+    if not queries:
+        raise ToolError("give 'part' (an LCSC code such as C2286 or an MPN) or 'parts'")
+    reports = catalog.lookup_many([str(q) for q in queries[:40]])
+    out: dict[str, Any] = {}
+    for query, report in reports.items():
+        if report.part is not None:
+            out[query] = report.part.to_dict(brief=not args.get("full"))
+        elif report.answered:
+            out[query] = {
+                "found": False,
+                "note": "no catalogue knows this part number"
+                + ("; it is not a valid LCSC code" if not is_lcsc_code(query) else ""),
+                "asked": report.describe(),
+            }
+        else:
+            out[query] = {
+                "found": False,
+                "note": "not verified: offline",
+                "asked": report.describe(),
+            }
+    return out
+
+
+def part_search(args: dict[str, Any], ctx: ToolContext) -> dict:
+    try:
+        results = default_catalog().search(
+            args["query"],
+            package=args.get("package"),
+            basic_only=bool(args.get("basic_only", False)),
+            in_stock=bool(args.get("in_stock", True)),
+            limit=int(args.get("limit") or 10),
+        )
+    except Offline as exc:
+        raise _offline_error(exc) from exc
+    return {
+        "query": args["query"],
+        "results": [p.to_dict(brief=True) for p in results],
+        "note": "sorted basic first, then by stock. Verify with part_lookup before writing an "
+        "LCSC/MPN field, and check the package against the footprint."
+        if results
+        else "no matches: use fewer words (MPN prefix, value + package) or drop filters",
+    }
+
+
+def parts_check(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.checks import summarize
+    from traceforge.kicad.pcb import read_board
+    from traceforge.kicad.project import discover
+    from traceforge.kicad.schematic import read_schematic
+    from traceforge.parts.verify import check_parts
+
+    ws = discover(ctx.workspace)
+    schematic = (
+        ctx.resolve(args["schematic"], must_exist=True) if args.get("schematic") else ws.schematic
+    )
+    if schematic is None:
+        raise ToolError("no schematic found")
+    pcb = ctx.resolve(args["pcb"], must_exist=True) if args.get("pcb") else ws.pcb
+    board = read_board(pcb) if pcb else None
+    findings, summary = check_parts(read_schematic(schematic), board)
+    return {"summary": summary, **summarize(findings)}
+
+
+def parts_verify(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.parts.report import brief, verify_design
+
+    folder = ctx.resolve(args["path"], must_exist=True) if args.get("path") else ctx.workspace
+    data = verify_design(folder)
+    ctx.state["parts_verified"] = data["all_verified"]
+    out = brief(data)
+    if out.get("report"):
+        out["report"] = ctx.display(Path(out["report"]))
+    return out
+
+
+def datasheet_fetch(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.parts.datasheet import fetch_datasheet, select
+
+    folder = ctx.workspace / ".traceforge" / "datasheets"
+    url = args.get("url")
+    name = None
+    local: Path | None = None
+    part_info = None
+    if args.get("path"):
+        local = ctx.resolve(args["path"], must_exist=True)
+    elif not url:
+        part = args.get("part")
+        if not part:
+            raise ToolError("give 'url', 'part' (LCSC code or MPN) or 'path'")
+        try:
+            info = default_catalog().lookup(part)
+        except Offline as exc:
+            raise _offline_error(exc) from exc
+        if info is None or not info.datasheet_url:
+            raise ToolError(f"no datasheet URL known for {part}; try web_search")
+        url, name = info.datasheet_url, f"{info.lcsc or ''}_{info.mpn}"
+        part_info = {"lcsc": info.lcsc, "mpn": info.mpn, "manufacturer": info.manufacturer}
+    try:
+        path, pages, outline = fetch_datasheet(folder, url=url, name=name, local=local)
+    except Offline as exc:
+        raise _offline_error(exc) from exc
+    except ProviderError as exc:
+        raise ToolError(str(exc)) from exc
+    result = select(
+        pages,
+        outline,
+        page_spec=args.get("pages"),
+        query=args.get("query"),
+        max_chars=int(args.get("max_chars") or 24_000),
+    )
+    result = {"saved": ctx.display(path), "source": url or str(local), **result}
+    if part_info:
+        result["part"] = part_info
+    return result
+
+
+def web_search_tool(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.parts.web import web_search
+
+    try:
+        answer = web_search(args["query"], limit=int(args.get("limit") or 8))
+    except Offline as exc:
+        raise _offline_error(exc) from exc
+    except ProviderError as exc:
+        raise ToolError(str(exc)) from exc
+    return answer.to_dict()
+
+
+def web_fetch_tool(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.parts.web import web_fetch
+
+    try:
+        return web_fetch(
+            args["url"],
+            max_chars=min(int(args.get("max_chars") or 20_000), 60_000),
+            offset=int(args.get("offset") or 0),
+            find=args.get("find"),
+        )
+    except Offline as exc:
+        raise _offline_error(exc) from exc
+    except ProviderError as exc:
+        raise ToolError(str(exc)) from exc
+
+
+def reference_projects(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.parts.web import reference_project_search
+
+    return reference_project_search(
+        args["query"], tool=args.get("tool") or "kicad", limit=int(args.get("limit") or 8)
+    )
+
+
+def _qty_list(args: dict[str, Any], key: str, default: tuple[int, ...]) -> tuple[int, ...]:
+    raw = args.get(key)
+    if not raw:
+        return default
+    try:
+        values = sorted({int(x) for x in raw})
+    except (TypeError, ValueError) as exc:
+        raise ToolError(f"{key} must be a list of whole numbers") from exc
+    if not values or values[0] < 1:
+        raise ToolError(f"{key} must be positive")
+    return tuple(values)
+
+
+def sourcing_compare(args: dict[str, Any], ctx: ToolContext) -> dict:
+    """Merged supplier comparison for one part."""
+    from traceforge.parts.supply import source_part
+
+    if not args.get("part"):
+        raise ToolError("give 'part' (LCSC code or MPN)")
+    result = source_part(
+        str(args["part"]),
+        qtys=_qty_list(args, "quantities", (1, 10, 100, 1000)),
+        currency=str(args.get("currency") or "USD"),
+        destination=str(args.get("country") or ""),
+    )
+    return result.to_dict()
+
+
+def parts_alternates(args: dict[str, Any], ctx: ToolContext) -> dict:
+    """Alternates by footprint and electrical match. Suggestions only."""
+    from traceforge.parts.alternates import find_alternates
+
+    if not args.get("part"):
+        raise ToolError("give 'part' (LCSC code or MPN)")
+    try:
+        return find_alternates(str(args["part"]), limit=int(args.get("limit") or 5)).to_dict()
+    except Offline as exc:
+        raise _offline_error(exc) from exc
+
+
+def sourcing_brief(args: dict[str, Any], ctx: ToolContext) -> dict:
+    """Cited sourcing brief for one part (HS code, distributors, risk, price bands, landed cost)."""
+    from traceforge.parts.brief import build_brief
+
+    if not args.get("part"):
+        raise ToolError("give 'part' (LCSC code or MPN)")
+    try:
+        brief = build_brief(
+            str(args["part"]),
+            country=str(args.get("country") or ""),
+            currency=str(args.get("currency") or "USD"),
+            qty=int(args.get("quantity") or 1000),
+        )
+    except Offline as exc:
+        raise _offline_error(exc) from exc
+    data = brief.to_dict()
+    if args.get("write"):
+        base = ctx.resolve(str(args["write"]), for_write=True)
+        base.parent.mkdir(parents=True, exist_ok=True)
+        base.with_suffix(".md").write_text(brief.to_markdown() + "\n", encoding="utf-8")
+        base.with_suffix(".json").write_text(
+            json.dumps(data, indent=1, default=str), encoding="utf-8"
+        )
+        data["written"] = [str(base.with_suffix(".md")), str(base.with_suffix(".json"))]
+    else:
+        data["markdown"] = brief.to_markdown()
+    return data
+
+
+def bom_cost(args: dict[str, Any], ctx: ToolContext) -> dict:
+    """Priced BOM roll-up (cheapest eligible supplier per line) and optional CSV exports."""
+    from traceforge.parts.bom import export_bom, load_bom, rollup
+    from traceforge.parts.fx import load_rates
+    from traceforge.parts.supply import source_many
+
+    path = ctx.resolve(str(args.get("path") or "."), must_exist=True)
+    try:
+        items = load_bom(path)
+    except (ValueError, OSError) as exc:
+        raise ToolError(str(exc)) from exc
+    boards = _qty_list(args, "board_quantities", (1, 10, 100, 1000))
+    currency = str(args.get("currency") or "USD")
+    fx = load_rates()
+    try:
+        sourcings = source_many(
+            [i.query for i in items if i.query],
+            qtys=tuple(sorted({q * i.qty for q in boards for i in items})),
+            currency=currency,
+            fx=fx,
+        )
+    except Offline as exc:
+        raise _offline_error(exc) from exc
+    roll = rollup(items, sourcings, boards, currency.upper())
+    out = roll.to_dict()
+    out["fx"] = fx.describe()
+    out["markdown"] = roll.to_markdown()
+    if args.get("export_dir"):
+        folder = ctx.resolve(str(args["export_dir"]), for_write=True)
+        folder.mkdir(parents=True, exist_ok=True)
+        written = []
+        for fmt in ("jlcpcb", "pcbway", "generic", "excel"):
+            target = folder / f"bom_{fmt}.csv"
+            target.write_text(
+                export_bom(items, fmt, sourcings, boards[0]), encoding="utf-8", newline=""
+            )
+            written.append(str(target))
+        out["written"] = written
+    return out
+
+
+PART_TOOLS = [
+    Tool(
+        "part_lookup",
+        "Look up parts live in the JLCPCB/LCSC catalogues (and Octopart/DigiKey/Mouser when "
+        "configured): manufacturer, MPN, package, pin count, stock, price, JLCPCB basic/"
+        "extended, datasheet URL, key attributes. Give an LCSC code (C2286) or MPN; 'parts' "
+        "checks many at once. Use it for every part number you write or review.",
+        {
+            "type": "object",
+            "properties": {
+                "part": {"type": "string"},
+                "parts": {"type": "array", "items": {"type": "string"}},
+                "full": {"type": "boolean", "description": "all attributes and price breaks"},
+            },
+        },
+        part_lookup,
+    ),
+    Tool(
+        "part_search",
+        "Search orderable parts by MPN prefix, value and package or keywords ('10k 0603 1%', "
+        "'100nF 0402', 'AMS1117-3.3', 'usb type-c 16p'). Returns JLCPCB basic parts first, then "
+        "by stock. Pick part numbers from these results, never from memory.",
+        {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "package": {"type": "string", "description": "e.g. 0603, SOT-23-5, SOIC-8"},
+                "basic_only": {"type": "boolean"},
+                "in_stock": {"type": "boolean", "description": "default true"},
+                "limit": {"type": "integer"},
+            },
+            "required": ["query"],
+        },
+        part_search,
+    ),
+    Tool(
+        "parts_check",
+        "Verify every LCSC/MPN in the project against the live catalogue: part exists, package "
+        "fits the footprint (size, SOIC width, pin count, pitch, SMD/THT), value and MPN match, "
+        "stock, lifecycle, basic vs extended. Returns P0-P3 findings with evidence.",
+        {
+            "type": "object",
+            "properties": {"schematic": {"type": "string"}, "pcb": {"type": "string"}},
+        },
+        parts_check,
+    ),
+    Tool(
+        "parts_verify",
+        "Verify every BOM line (part exists, package vs footprint, pin count, datasheet pinout "
+        "vs symbol pins and footprint pads, stock, basic/extended) and write "
+        ".traceforge/reports/parts-verification.md/.json. The design is not finished until "
+        "this reports 'all parts verified'.",
+        {
+            "type": "object",
+            "properties": {"path": {"type": "string", "description": "project folder"}},
+        },
+        parts_verify,
+    ),
+    Tool(
+        "datasheet_fetch",
+        "Download a datasheet (by url, by part via its catalogue datasheet, or a local PDF path) "
+        "to .traceforge/datasheets/ and return text: the pages you ask for ('1-3,12'), the pages "
+        "that best match 'query' (e.g. 'package dimensions 8S2', 'absolute maximum', 'typical "
+        "application'), or by default the first pages and the outline.",
+        {
+            "type": "object",
+            "properties": {
+                "url": {"type": "string"},
+                "part": {"type": "string", "description": "LCSC code or MPN"},
+                "path": {"type": "string", "description": "a PDF already in the workspace"},
+                "pages": {"type": "string"},
+                "query": {"type": "string"},
+                "max_chars": {"type": "integer"},
+            },
+        },
+        datasheet_fetch,
+    ),
+    Tool(
+        "sourcing_compare",
+        "Merged supplier comparison for one part across every configured source (JLCPCB, LCSC, "
+        "jlcsearch, plus DigiKey/Mouser/Nexar when keyed): price breaks, stock, MOQ, lead time, "
+        "lifecycle, best price per quantity and a recommended supplier, in one currency with the "
+        "exchange-rate table named.",
+        {
+            "type": "object",
+            "properties": {
+                "part": {"type": "string", "description": "LCSC code or MPN"},
+                "quantities": {"type": "array", "items": {"type": "integer"}},
+                "currency": {"type": "string"},
+                "country": {"type": "string"},
+            },
+            "required": ["part"],
+        },
+        sourcing_compare,
+    ),
+    Tool(
+        "parts_alternates",
+        "Alternates by footprint and electrical match (passives: value, tolerance, rating, "
+        "package, dielectric; MCUs: pin-compatible family suggestions with confidence). Each "
+        "carries reasons and differences. Suggestions only: never substitute without telling the user.",
+        {
+            "type": "object",
+            "properties": {"part": {"type": "string"}, "limit": {"type": "integer"}},
+            "required": ["part"],
+        },
+        parts_alternates,
+    ),
+    Tool(
+        "sourcing_brief",
+        "Cited sourcing brief for one part: suppliers, HS code with rationale (a guide to confirm "
+        "with the customs broker), authorised distributors, single-source risk, volume price bands "
+        "and a landed-cost estimate with the arithmetic. Pass 'write' (path without extension) to "
+        "save Markdown and JSON.",
+        {
+            "type": "object",
+            "properties": {
+                "part": {"type": "string"},
+                "country": {"type": "string", "description": "destination, e.g. IN"},
+                "quantity": {"type": "integer"},
+                "currency": {"type": "string"},
+                "write": {"type": "string"},
+            },
+            "required": ["part"],
+        },
+        sourcing_brief,
+        ToolKind.WRITE,
+        "write",
+    ),
+    Tool(
+        "bom_cost",
+        "Price a whole BOM (design.yaml, KiCad schematic, project folder or BOM CSV): cheapest "
+        "eligible supplier per line and totals at 1/10/100/1000 boards. 'export_dir' also writes "
+        "JLCPCB, PCBWay, generic and Excel CSV BOMs.",
+        {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "board_quantities": {"type": "array", "items": {"type": "integer"}},
+                "currency": {"type": "string"},
+                "export_dir": {"type": "string"},
+            },
+        },
+        bom_cost,
+        ToolKind.WRITE,
+        "export_dir",
+    ),
+    Tool(
+        "web_search",
+        "Search the web (read-only): app notes, errata, reference values, part comparisons. "
+        "Returns titles, URLs, snippets and, for some providers, a cited answer.",
+        {
+            "type": "object",
+            "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+            "required": ["query"],
+        },
+        web_search_tool,
+    ),
+    Tool(
+        "web_fetch",
+        "Fetch a public web page or PDF as plain text (read-only). Use 'find' to return only "
+        "the passages around a phrase, or offset/max_chars to page through long documents.",
+        {
+            "type": "object",
+            "properties": {
+                "url": {"type": "string"},
+                "find": {"type": "string"},
+                "offset": {"type": "integer"},
+                "max_chars": {"type": "integer"},
+            },
+            "required": ["url"],
+        },
+        web_fetch_tool,
+    ),
+    Tool(
+        "reference_project_search",
+        "Find open-source reference designs (GitHub, OSHWLab, Hackaday.io) that use a part or "
+        "implement a circuit block, to compare against proven schematics and values.",
+        {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "e.g. 'ATtiny85 USB-C', 'CH340C'"},
+                "tool": {"type": "string", "enum": ["kicad", "altium", "any"]},
+                "limit": {"type": "integer"},
+            },
+            "required": ["query"],
+        },
+        reference_projects,
+    ),
+]