klayout-tools 0.1.0__py3-none-any.whl

klayout_tools/__init__.py

@@ -0,0 +1,3 @@
+"""klayout-tools: tools for AI agents to work with IC layout."""
+
+__version__ = "0.0.1"

klayout_tools/cells.py

@@ -0,0 +1,148 @@
+"""Enumerate the cell hierarchy of a GDSII/OASIS stream.
+
+Pure library: :func:`cells_report` returns plain Python data (a ``dict`` of
+JSON-serialisable primitives) and never prints. Serialisation and human-readable
+formatting live in the CLI command module so this function stays reusable (e.g.
+by a future MCP server).
+
+Headless invariant: uses the pip ``klayout`` package's batch database API
+(``klayout.db``) only — no GUI, no Qt. Runnable in CI.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+class CellsError(Exception):
+    """Raised when a layout file cannot be read or enumerated.
+
+    The CLI turns this into a clean stderr message + exit code 1, never a
+    traceback.
+    """
+
+
+def cells_report(path: str, top: bool = False) -> dict[str, Any]:
+    """Enumerate the cell hierarchy of a GDSII or OASIS stream.
+
+    KLayout auto-detects the stream format on read, so both ``.gds`` and
+    ``.oas`` inputs are handled by the same code path.
+
+    Returns a dict matching the documented JSON schema (see
+    ``docs/cli/cells.md``)::
+
+        {
+            "schema_version": 1,
+            "file": <path as provided>,
+            "dbu_um": <database unit in micrometres, float>,
+            "cell_count": <total cells in the whole layout, int>,
+            "top_cell_count": <total top cells in the whole layout, int>,
+            "cells": [
+                {
+                    "name": str,
+                    "index": int,
+                    "is_top": bool,
+                    "shapes": int,
+                    "instances": int,
+                    "children": [str, ...],
+                    "parents": [str, ...],
+                    "bbox_um": {"left": float, "bottom": float,
+                                "right": float, "top": float} | None,
+                },
+                ...
+            ],
+        }
+
+    ``cells`` is sorted by ``index`` ascending for deterministic output.
+    ``cell_count``/``top_cell_count`` always describe the whole layout,
+    regardless of the ``top`` filter. When ``top`` is true, ``cells`` is
+    narrowed to entries with ``is_top: True`` only.
+
+    Field semantics:
+
+    - ``shapes`` is the count of shapes owned by this cell's own definition,
+      summed across all layers — not multiplied by instantiation (same
+      convention as ``klt layers``' ``shapes`` field).
+    - ``instances`` is the count of child-instance *placement records*
+      (``Cell.each_inst()``) — an arrayed instance counts as one placement
+      record, not its expanded row-by-column total.
+    - ``children``/``parents`` are deduplicated, sorted cell names one level
+      of instantiation away (direct only, not transitive).
+    - ``bbox_um`` is ``None`` when the cell (including its children) has no
+      geometry at all, rather than a degenerate/inverted box.
+
+    Raises :class:`CellsError` if the file is missing, unreadable, or not a
+    recognisable layout stream.
+    """
+    if not os.path.exists(path):
+        raise CellsError(f"file not found: {path}")
+    if os.path.isdir(path):
+        raise CellsError(f"not a file: {path}")
+
+    # Imported lazily so that `klt --version` and argument parsing do not pay
+    # the cost of loading the KLayout database module.
+    import klayout.db as kdb
+
+    layout = kdb.Layout()
+    try:
+        layout.read(path)
+    except Exception as exc:  # klayout raises RuntimeError for bad/unknown streams
+        raise CellsError(f"could not read layout '{path}': {exc}") from exc
+
+    top_cell_indices = {cell.cell_index() for cell in layout.top_cells()}
+
+    cells: list[dict[str, Any]] = []
+    for cell in layout.each_cell():
+        index = cell.cell_index()
+        shape_count = sum(
+            cell.shapes(layer_index).size() for layer_index in layout.layer_indexes()
+        )
+        instance_count = sum(1 for _ in cell.each_inst())
+        children = sorted(
+            {layout.cell(child_index).name for child_index in cell.each_child_cell()}
+        )
+        parents = sorted(
+            {layout.cell(parent_index).name for parent_index in cell.each_parent_cell()}
+        )
+        bbox = cell.dbbox()
+        bbox_um = (
+            None
+            if bbox.empty()
+            else {
+                "left": bbox.left,
+                "bottom": bbox.bottom,
+                "right": bbox.right,
+                "top": bbox.top,
+            }
+        )
+
+        cells.append(
+            {
+                "name": cell.name,
+                "index": index,
+                "is_top": index in top_cell_indices,
+                "shapes": shape_count,
+                "instances": instance_count,
+                "children": children,
+                "parents": parents,
+                "bbox_um": bbox_um,
+            }
+        )
+
+    cells.sort(key=lambda entry: entry["index"])
+
+    cell_count = len(cells)
+    top_cell_count = len(top_cell_indices)
+
+    if top:
+        cells = [entry for entry in cells if entry["is_top"]]
+
+    return {
+        "schema_version": 1,
+        "file": path,
+        "dbu_um": layout.dbu,
+        "cell_count": cell_count,
+        "top_cell_count": top_cell_count,
+        "cells": cells,
+    }

klayout_tools/cli/__init__.py

@@ -0,0 +1,28 @@
+"""klt — CLI entry point.
+
+Subcommands live in ``<verb>_cmd.py`` modules (mirroring kicad-tools' CLI
+package). The argument parser is built in :mod:`parser`; this module dispatches
+to the selected subcommand. Every subcommand supports ``--format json`` — JSON
+is the API.
+"""
+
+import sys
+
+from .. import __version__
+from .parser import create_parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    # No subcommand: preserve the scaffold status blurb (and exit 0).
+    if getattr(args, "func", None) is None:
+        print(f"klt {__version__} — scaffold; run `klt --help` for available commands")
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

klayout_tools/cli/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m klayout_tools.cli``."""
+
+import sys
+
+from . import main
+
+if __name__ == "__main__":
+    sys.exit(main())

klayout_tools/cli/cells_cmd.py

@@ -0,0 +1,84 @@
+"""``klt cells`` command: serialise the cells report as text or JSON.
+
+Output goes through the shared envelope helpers in :mod:`.output`, as with
+every other ``klt`` subcommand — see ``docs/json-contract.md``.
+"""
+
+import argparse
+
+from ..cells import CellsError, cells_report
+from .output import emit_error, emit_success
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        report = cells_report(args.file, top=args.top)
+    except CellsError as exc:
+        return emit_error("cells", str(exc), args.format)
+
+    emit_success(report, args.format, _print_text)
+    return 0
+
+
+def _print_text(report: dict) -> None:
+    print(f"file: {report['file']}")
+    print(f"dbu_um: {report['dbu_um']}")
+    print(f"cells: {report['cell_count']}")
+    print(f"top_cells: {report['top_cell_count']}")
+
+    cells = report["cells"]
+    if not cells:
+        return
+
+    def fmt_bbox(bbox: dict | None) -> str:
+        if bbox is None:
+            return "-"
+        return (
+            f"({bbox['left']:g}, {bbox['bottom']:g}, "
+            f"{bbox['right']:g}, {bbox['top']:g})"
+        )
+
+    rows = [
+        (
+            str(entry["index"]),
+            entry["name"],
+            "yes" if entry["is_top"] else "no",
+            str(entry["shapes"]),
+            str(entry["instances"]),
+            ",".join(entry["children"]) if entry["children"] else "-",
+            ",".join(entry["parents"]) if entry["parents"] else "-",
+            fmt_bbox(entry["bbox_um"]),
+        )
+        for entry in cells
+    ]
+    headers = (
+        "index",
+        "name",
+        "is_top",
+        "shapes",
+        "instances",
+        "children",
+        "parents",
+        "bbox_um",
+    )
+    widths = [
+        max(len(headers[col]), max(len(row[col]) for row in rows))
+        for col in range(len(headers))
+    ]
+
+    def fmt(row: tuple[str, ...]) -> str:
+        # Numeric-ish columns (index, is_top, shapes, instances) right-aligned;
+        # name/children/parents/bbox_um left-aligned.
+        right_aligned = {0, 2, 3, 4}
+        return "  ".join(
+            row[col].rjust(widths[col])
+            if col in right_aligned
+            else row[col].ljust(widths[col])
+            for col in range(len(headers))
+        )
+
+    print()
+    print(fmt(headers))
+    print("  ".join("-" * widths[col] for col in range(len(headers))))
+    for row in rows:
+        print(fmt(row))

klayout_tools/cli/drc_cmd.py

@@ -0,0 +1,59 @@
+"""``klt drc`` command: serialise the DRC report as text or JSON.
+
+Output goes through the shared envelope helpers in :mod:`.output`, as with
+every other ``klt`` subcommand — see ``docs/json-contract.md``.
+
+Exit codes (see ``docs/cli/drc.md`` for the full table):
+    0 - ran clean, no violations
+    1 - failed to run (bad file, unknown deck, engine error) — returned by
+        ``emit_error`` as ``output.ERROR_EXIT_CODE``
+    3 - ran successfully, violations found
+(2 is reserved for argparse usage errors, as with every other ``klt`` subcommand.)
+"""
+
+import argparse
+
+from ..drc import DrcError, run_drc
+from .output import emit_error, emit_success
+
+EXIT_CLEAN = 0
+EXIT_VIOLATIONS = 3
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        report = run_drc(args.file, args.deck)
+    except DrcError as exc:
+        return emit_error("drc", str(exc), args.format)
+
+    emit_success(report, args.format, _print_text)
+
+    return EXIT_VIOLATIONS if report["status"] == "violations" else EXIT_CLEAN
+
+
+def _print_text(report: dict) -> None:
+    print(f"file: {report['file']}")
+    print(f"deck: {report['deck']}")
+    print(f"dbu_um: {report['dbu_um']}")
+    print(f"status: {report['status']}")
+    print(f"violations: {report['violation_count']}")
+
+    rule_counts = report["rule_counts"]
+    if rule_counts:
+        print()
+        print("rule_counts:")
+        for rule_id in sorted(rule_counts):
+            print(f"  {rule_id}: {rule_counts[rule_id]}")
+
+    violations = report["violations"]
+    if not violations:
+        return
+
+    print()
+    for entry in violations:
+        bbox = entry["bbox"]
+        print(
+            f"{entry['rule']}  {entry['cell']}  {entry['layer']}  "
+            f"({bbox['left']},{bbox['bottom']})-({bbox['right']},{bbox['top']})  "
+            f"{entry['description']}"
+        )

klayout_tools/cli/layers_cmd.py

@@ -0,0 +1,54 @@
+"""``klt layers`` command: serialise the layers report as text or JSON."""
+
+import argparse
+
+from ..layers import LayersError, layers_report
+from .output import emit_error, emit_success
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        report = layers_report(args.file)
+    except LayersError as exc:
+        return emit_error("layers", str(exc), args.format)
+
+    emit_success(report, args.format, _print_text)
+    return 0
+
+
+def _print_text(report: dict) -> None:
+    print(f"file: {report['file']}")
+    print(f"dbu_um: {report['dbu_um']}")
+    print(f"layers: {report['layer_count']}")
+
+    layers = report["layers"]
+    if not layers:
+        return
+
+    rows = [
+        (
+            str(entry["layer"]),
+            str(entry["datatype"]),
+            entry["name"] if entry["name"] is not None else "-",
+            str(entry["shapes"]),
+        )
+        for entry in layers
+    ]
+    headers = ("layer", "datatype", "name", "shapes")
+    widths = [
+        max(len(headers[col]), max(len(row[col]) for row in rows))
+        for col in range(len(headers))
+    ]
+
+    def fmt(row: tuple[str, ...]) -> str:
+        # layer/datatype/shapes right-aligned (numeric), name left-aligned.
+        return "  ".join(
+            row[col].rjust(widths[col]) if col != 2 else row[col].ljust(widths[col])
+            for col in range(len(headers))
+        )
+
+    print()
+    print(fmt(headers))
+    print("  ".join("-" * widths[col] for col in range(len(headers))))
+    for row in rows:
+        print(fmt(row))

klayout_tools/cli/output.py

@@ -0,0 +1,79 @@
+"""Shared JSON/text output helper for ``klt`` subcommands.
+
+Every ``*_cmd.py`` module emits through :func:`emit_success` /
+:func:`emit_error` instead of hand-rolling ``json.dump``/``print`` — this is
+the one place that knows the documented envelope shape (see
+``docs/json-contract.md``).
+
+Design notes (additive envelope, not a wrapping one):
+
+- Success payloads stay **flat** at the top level (no ``{"result": {...}}``
+  nesting) so existing, already-documented command shapes (e.g. ``klt
+  layers``) are unaffected. Commands add their own ``schema_version`` field to
+  the payload dict *before* calling :func:`emit_success` — this module does
+  not inject it, since the version is owned by the library function that
+  builds the payload (see ``layers.py``'s docstring on MCP reuse).
+- ``--format json`` output on success goes to **stdout only**; on error, the
+  JSON error object goes to **stderr**, and stdout is left empty. This means
+  a caller never has to inspect stdout content to distinguish success from
+  failure under ``--format json`` — check the exit code.
+- ``--format text`` is a courtesy rendering, not the contract: success calls
+  a command-supplied ``text_renderer`` callback, and errors print a plain
+  ``klt <command>: <message>`` line to stderr, matching pre-existing
+  behaviour.
+- Exit code ``1`` is returned by :func:`emit_error` for application-level
+  errors. Argparse-level usage errors (exit code ``2``) are raised by
+  argparse itself before a command's ``run()`` executes, so they are out of
+  scope for this helper by construction.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+
+#: Application-level error exit code (as opposed to argparse's usage-error 2).
+ERROR_EXIT_CODE = 1
+
+
+def emit_success(
+    payload: dict,
+    format: str,
+    text_renderer: Callable[[dict], None],
+) -> None:
+    """Emit a successful command result in the requested ``format``.
+
+    ``format == "json"`` writes ``payload`` as indented JSON to stdout (plus a
+    trailing newline). ``format == "text"`` delegates to ``text_renderer``,
+    which is responsible for printing whatever human-readable rendering the
+    command defines; ``text_renderer`` is not part of the JSON contract.
+    """
+    if format == "json":
+        json.dump(payload, sys.stdout, indent=2)
+        print()
+    else:
+        text_renderer(payload)
+
+
+def emit_error(command: str, message: str, format: str) -> int:
+    """Emit an application-level error and return the exit code to use.
+
+    ``format == "json"`` writes the documented error envelope to stderr:
+    ``{"schema_version": 1, "error": {"command": ..., "message": ...}}``.
+    ``format == "text"`` writes the pre-existing plain-text stderr line,
+    ``klt <command>: <message>``.
+
+    Always returns :data:`ERROR_EXIT_CODE` (``1``) so a command's ``run()``
+    can simply ``return emit_error(...)``.
+    """
+    if format == "json":
+        error_payload = {
+            "schema_version": 1,
+            "error": {"command": command, "message": message},
+        }
+        json.dump(error_payload, sys.stderr, indent=2)
+        print(file=sys.stderr)
+    else:
+        print(f"klt {command}: {message}", file=sys.stderr)
+    return ERROR_EXIT_CODE

klayout_tools/cli/parser.py

@@ -0,0 +1,222 @@
+"""Argument parser for the ``klt`` CLI.
+
+``--format {text,json}`` is a *per-subcommand* option (kicad-tools convention),
+defaulting to ``text``. New subcommands register themselves here and point their
+``func`` default at a ``run(args) -> int`` handler.
+"""
+
+import argparse
+import sys
+
+from .. import __version__
+from . import cells_cmd, drc_cmd, layers_cmd, pdk_cmd, stats_cmd
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="klt",
+        description="Tools for AI agents to work with IC layout.",
+    )
+    parser.add_argument("--version", action="version", version=f"klt {__version__}")
+    # No default handler: absence of a subcommand is handled by main().
+    parser.set_defaults(func=None)
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    layers_parser = subparsers.add_parser(
+        "layers",
+        help="enumerate layers of a GDSII/OASIS stream",
+        description=(
+            "Report the layer/datatype pairs, names, and per-cell-definition "
+            "shape counts of a GDSII or OASIS layout file."
+        ),
+    )
+    layers_parser.add_argument("file", help="path to a GDSII or OASIS layout file")
+    layers_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    layers_parser.set_defaults(func=layers_cmd.run)
+
+    stats_parser = subparsers.add_parser(
+        "stats",
+        help="report area, density, and polygon/vertex counts of a GDSII/OASIS stream",
+        description=(
+            "Report bounding box, drawn area, density, and polygon/vertex "
+            "counts of a GDSII or OASIS layout file, in total and optionally "
+            "per layer."
+        ),
+    )
+    stats_parser.add_argument("file", help="path to a GDSII or OASIS layout file")
+    stats_parser.add_argument(
+        "--per-layer",
+        action="store_true",
+        help="also report the same statistics broken down per layer",
+    )
+    stats_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    stats_parser.set_defaults(func=stats_cmd.run)
+
+    cells_parser = subparsers.add_parser(
+        "cells",
+        help="report the cell hierarchy of a GDSII/OASIS stream",
+        description=(
+            "Report the cell hierarchy of a GDSII or OASIS layout file: "
+            "top-cell status, per-cell shape/instance counts, direct "
+            "children/parents, and bounding box."
+        ),
+    )
+    cells_parser.add_argument("file", help="path to a GDSII or OASIS layout file")
+    cells_parser.add_argument(
+        "--top",
+        action="store_true",
+        help="only report top cells (cells with no parent instances)",
+    )
+    cells_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    cells_parser.set_defaults(func=cells_cmd.run)
+
+    drc_parser = subparsers.add_parser(
+        "drc",
+        help="run a headless DRC deck against a GDSII/OASIS stream",
+        description=(
+            "Run a DRC rule deck against a GDSII or OASIS layout file and "
+            "report violations as structured data. Runs fully headless via "
+            "KLayout's native Region check primitives — no GUI, no Qt, no "
+            "standalone klayout binary."
+        ),
+    )
+    drc_parser.add_argument("file", help="path to a GDSII or OASIS layout file")
+    drc_parser.add_argument(
+        "--deck",
+        required=True,
+        help=(
+            "DRC deck to run (currently: sky130, gf180mcu). Not validated by "
+            "argparse -- an unknown deck name exits 1 with a clean error, "
+            "per docs/cli/drc.md's exit-code contract, rather than "
+            "argparse's usage-error exit 2."
+        ),
+    )
+    drc_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    drc_parser.set_defaults(func=drc_cmd.run)
+
+    _add_pdk_parser(subparsers)
+
+    return parser
+
+
+def _add_pdk_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``pdk`` verb with nested ``find``/``list``/``env`` subcommands.
+
+    The other verbs are flat; ``pdk`` groups discovery operations under one
+    verb (kicad-tools convention for multi-operation capabilities), so it uses
+    argparse sub-subparsers. Each ``--format`` stays a per-subcommand option,
+    matching the flat verbs.
+    """
+    pdk_parser = subparsers.add_parser(
+        "pdk",
+        help="discover and resolve an installed PDK",
+        description=(
+            "Locate an installed open_pdks-layout PDK (open_pdks, volare, or "
+            "ciel) and report its root, variant, version stamp, and per-tool "
+            "asset directories as structured data. This is the one shared "
+            "PDK_ROOT resolver every downstream tool imports instead of "
+            "re-implementing the lookup. Fully headless; safe in CI."
+        ),
+    )
+    pdk_sub = pdk_parser.add_subparsers(dest="pdk_command", metavar="<subcommand>")
+
+    def _no_subcommand(_args: argparse.Namespace) -> int:
+        pdk_parser.print_help(sys.stderr)
+        return 2
+
+    pdk_parser.set_defaults(func=_no_subcommand)
+
+    find_parser = pdk_sub.add_parser(
+        "find",
+        help="resolve one PDK install/variant and report its paths",
+        description=(
+            "Resolve a single PDK install and variant via the documented "
+            "resolution order and emit its root, variant, version, how it was "
+            "resolved, and its per-tool asset directories."
+        ),
+    )
+    find_parser.add_argument(
+        "--pdk",
+        help="variant to resolve (e.g. sky130A); overrides $PDK",
+    )
+    find_parser.add_argument(
+        "--pdk-root",
+        dest="pdk_root",
+        help="explicit install root; overrides $PDK_ROOT and the search order",
+    )
+    find_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    find_parser.set_defaults(func=pdk_cmd.run_find)
+
+    list_parser = pdk_sub.add_parser(
+        "list",
+        help="enumerate every PDK install and variant discovered",
+        description=(
+            "Enumerate every install and variant found across the full search "
+            "order. An empty result is success (exit 0), not an error."
+        ),
+    )
+    list_parser.add_argument(
+        "--pdk-root",
+        dest="pdk_root",
+        help="restrict the scan to this install root",
+    )
+    list_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    list_parser.set_defaults(func=pdk_cmd.run_list)
+
+    env_parser = pdk_sub.add_parser(
+        "env",
+        help="emit the resolved paths as eval-able shell exports",
+        description=(
+            "Emit the resolved install as shell `export` lines "
+            '(`eval "$(klt pdk env)"`) so an interactive simulator or '
+            "schematic-editor session uses the same install the automated "
+            "tooling picked. --format json emits the same payload as `find`."
+        ),
+    )
+    env_parser.add_argument(
+        "--pdk",
+        help="variant to resolve (e.g. sky130A); overrides $PDK",
+    )
+    env_parser.add_argument(
+        "--pdk-root",
+        dest="pdk_root",
+        help="explicit install root; overrides $PDK_ROOT and the search order",
+    )
+    env_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text; text emits shell exports)",
+    )
+    env_parser.set_defaults(func=pdk_cmd.run_env)