michele/periscope
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Strengthen pintable layout_rules skill and refresh empty extractions.

Browse Source 
Treat PCB/application layout guidance as a first-class extract, keep those pages in PDF trim, and re-run IC extraction once when rules are still empty under older model_version.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
michele
2026-09-13 18:01:15 +02:00
co-authored by Cursor
parent 86121e6547
commit 21e2be1cd0
10 changed files with 332 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/extract-pintable/SKILL.md
+123 -54
View File
@@ -1,94 +1,163 @@
---
skill_name: extract-pintable
description: Extract pin table, package info, and component subtype from an IC datasheet PDF. Returns structured data via the save_pintable tool.
description: Extract pin table, package info, absolute-maximum ratings, layout_rules, and component subtype from an IC datasheet PDF. Returns structured data via the save_pintable tool.
---
# Extract Pin Table & Variant Info
Extract the pin table and variant/ordering information from a component datasheet and return it as structured JSON via the `save_pintable` tool.
Extract structured data from an IC datasheet and return it via the `save_pintable` tool.
**Priority order:** (1) complete pin table for the MPN package, (2) `layout_rules` from PCB / typical-application pages, (3) package + abs-max + subtype.
## Steps
### 1. Read the datasheet PDF
The datasheet PDF is provided in the user message. Focus on these sections:
- **Pin configuration / pin assignment table** — This is the primary target. Look for tables listing pin number, pin name, description, and alternate functions.
- **Ordering information / part number decoder** — Decode what each segment of the MPN means (package, temperature grade, packing, output voltage, etc.)
- **Package information** — Pin count, package type (QFP, BGA, SOT-23, etc.)
Focus on these sections (figures count as evidence):
- **Pin configuration / pin assignment table** — primary target
- **Ordering information / part number decoder**
- **Package information**
- **PCB layout / layout guidelines / land pattern notes**
- **Typical application / reference design** (placement callouts near caps, vias, keepouts)
- **Absolute maximum ratings**
### 2. Extract the pin table
For every pin on the component, extract:
- `number` (int or str) — The pin number, or BGA ball coordinate like `"A3"`
- `name` (str) — The pin name exactly as printed in the datasheet (e.g., `"VDD"`, `"PA0/SPI0_CLK"`)
- `description` (str or null) — A brief description if the datasheet provides one
- `functions` (list[str] or null) — Alternate/multiplexed functions if the pin supports them
For every pin:
- `number` (int or str) — pin number, or BGA ball like `"A3"`
- `name` (str) — verbatim from the datasheet (e.g. `"VDD"`, `"PA0/SPI0_CLK"`)
- `description` (str or null)
- `functions` (list[str] or null) — alternate/mux functions
Rules for pin extraction:
- Include ALL pins — power, ground, NC, and signal pins
- Use pin names verbatim from the datasheet — do not rename or normalize
- For multiplexed pins, put the primary name in `name` and alternates in `functions`
Rules:
- Include ALL pins — power, ground, NC, exposed pad / EP
- Names verbatim — do not rename or normalize
- Multiplexed pins: primary in `name`, alternates in `functions`
- If the datasheet has per-package tables, use the package matching the MPN
- Off-by-one pin numbers break everything downstream — double-check
Optional extras (omit if the PDF does not show them):
**Modules vs bare die (critical).** MPNs containing `WROOM`, `WROVER`, `MODULE`, `MOD-`, or `SIP` are *modules*. Extract the **module landing-pad table** (schematic pins). Do **not** extract the SoC/QFN ball map from a nested chip chapter.
- Espressif WROOM: pin 1 is GND. Pin 1 named `ANT`, `CHIP_PU`, or `XTAL_*` means you grabbed the die table — invalid.
- Crystal, RF antenna, and flash on a WROOM module are **inside the can**; they must not appear as schematic pin numbers.
Optional extras (omit if absent):
- `internal_features.pullup_pins` / `esd_clamp_pins` / `analog_switch` from the **block diagram** only.
- `layout_rules` from **PCB layout / typical application** pages. `kind` is only `decoupling_proximity`, `thermal_via`, `keepout`, or `length_match` (intra-pair skew mm). Set `max_distance_mm` only when the document states a number — do not invent JEDEC or USB millimetres.
Rules for pin extraction:`
- If the datasheet has separate tables for different packages, extract for the package matching the MPN
- Pay careful attention to pin numbering — off-by-one errors here break everything downstream
- **Modules vs bare die (critical).** MPNs containing `WROOM`, `WROVER`, `MODULE`, `MOD-`, or `SIP` are *modules*. Extract the **module landing-pad table** (connector pins the schematic uses). Do **not** extract the SoC/QFN ball map from a nested chip chapter or a sibling chip-only PDF.
- Espressif WROOM: pin 1 is GND (often a group of GND pads). Pin 1 named `ANT`, `CHIP_PU`, or `XTAL_*` means you grabbed the bare ESP32 die table — that will mark every module GND as “antenna shorted” and is invalid.
- Crystal, RF antenna, and flash on a WROOM module are **inside the can**; they must not appear as schematic pin numbers.
### 3. Extract layout_rules (required scan — empty OK)
### 3. Extract package info
You **must** look for layout guidance. Emit `layout_rules` as a list. Use `[]` only after scanning layout / application / thermal pages and finding no placement guidance.
Decode the MPN and package details into a single `PackageInfo`:
- `base_family` (str) — The base part family (e.g., `"MSPM0G3507"` from `"MSPM0G3507SPTR"`)
- `package` (str) — Package name (e.g., `"LQFP-48"`, `"SOT-23-5"`)
- `pin_count` (int) — Number of pins
- `description` (str) — Human-readable decoding of the full MPN (e.g., `"MSPM0G3507, 48-pin LQFP, tape & reel"`)
#### Where to look
- Headings: “PCB Layout”, “Layout Guidelines”, “Layout Considerations”, “Board Layout”, “Land Pattern”
- “Typical Application”, “Application Circuit”, “Reference Design”
- Thermal / EP / exposed-pad via recommendations
- Callouts on application figures (“place CIN within 2 mm of VIN”)
Look for an "Ordering Information" or "Device Information" table in the datasheet — most datasheets have one.
#### Allowed `kind` (closed set)
| kind | Use when |
| --- | --- |
| `decoupling_proximity` | Bypass / decoupling / input / output cap near a supply or pin |
| `thermal_via` | Vias under exposed pad / thermal pad / EP |
| `keepout` | Keep foreign nets, digital return, or copper out of a region |
| `length_match` | Intra-pair skew / matched length limit in mm |
### 4. Extract absolute maximum ratings
#### Fields
- `pin` — number or name as printed (`"5"`, `"VIN"`, `"VDD"`, `"EP"`)
- `cap_value_hint` — only if shown (`"100nF"`, `"10µF"`)
- `max_distance_mm` — **number only if the PDF states millimetres**
- OK: “within 2 mm”, “< 5 mm”, “no more than 3 mm from the pin” → `2` / `5` / `3`
- NOT OK as a number: “as close as possible”, “close to the pin”, “adjacent”, “nearby” → set `max_distance_mm: null` and keep the rule with a `note`
- **Never invent** JEDEC, USB, IPC, or “standard 3 mm / 5 mm” distances
- `same_layer` — `true`/`false` only if text says same side / opposite side of the board; else null
- `min_via_count` — integer only if stated (“at least 4 vias”)
- `net_class` / `note` — short quote of the guidance
- `source_page` — 1-based page of the guidance (required when you emit a rule)
Copy the **Absolute Maximum Ratings** table (not Recommended Operating Conditions). For each row that a reviewer would need to compare against the schematic rails:
#### Examples
- `parameter` (str) — as printed (`VCC`, `VIN`, `I/O pin voltage`, `Storage temperature`, …)
- `min` / `max` (number or null) — numeric limit; omit the other side if the table only lists one
- `unit` (str) — `V`, `mA`, `°C`, …
- `source_page` (int) — 1-based datasheet page of that row
Numeric proximity (copy the millimetre from the PDF):
Include supply voltages, pin/input voltages, input current, and temperature. Skip ESD *human-body-model / IEC contact-discharge kV* rows unless they are the only voltage limit given. Do not invent numbers; if the table is a raster with no readable values, return an empty array.
```json
{
"kind": "decoupling_proximity",
"pin": "VIN",
"cap_value_hint": "10uF",
"max_distance_mm": 2.0,
"same_layer": true,
"note": "Place CIN within 2 mm of VIN",
"source_page": 14
}
```
**ESD / TVS / protection ICs (`ic.protection.esd` and similar):** also copy from Electrical Characteristics (not only abs-max):
Proximity without a millimetre (still emit the rule):
- Working / reverse working voltage **Vrwm** (or V_RWM / "operating voltage") as a **signed** min/max in volts — e.g. bidirectional ±13 V is `min: -13`, `max: 13`, `unit: "V"`.
- One extra row whose `parameter` states polarity/topology as printed (`bidirectional`, `unidirectional`, `back-to-back`), `unit: "—"`, min/max omitted. Do **not** infer unidirectional from "IO" pins that list GND as the reference pin.
```json
{
"kind": "decoupling_proximity",
"pin": "VDD",
"cap_value_hint": "100nF",
"max_distance_mm": null,
"note": "Place decoupling capacitor as close as possible to VDD",
"source_page": 22
}
```
### 5. Assign component subtype (taxonomy)
Thermal vias:
The existing IC taxonomy subtypes are provided in the system prompt under `EXISTING IC TAXONOMY SUBTYPES`. Pick the best matching subtype based on the component's MPN, package info, and pin names.
```json
{
"kind": "thermal_via",
"pin": "EP",
"min_via_count": 4,
"note": "Use at least 4 thermal vias in the exposed pad",
"source_page": 18
}
```
If no existing subtype fits, propose a new one following the dot-notation convention (`ic.{category}.{specific}`).
#### Hard negatives
- Do not invent land-pattern pad sizes from the mechanical drawing alone
- Do not emit `length_match` for USB/HDMI/PCIe unless the **this** datasheet states a skew/length number
- Do not use kinds outside the closed set
- One rule per distinct pin/guidance; prefer supply pins that show caps in the application figure
Set the chosen subtype on the `component_subtype` field.
### 4. Extract package info
### 6. Quality checks
- `base_family` — e.g. `"MSPM0G3507"` from `"MSPM0G3507SPTR"`
- `package` — e.g. `"LQFP-48"`, `"SOT-23-5"`
- `pin_count` (int)
- `description` — human-readable MPN decode
Before producing output, verify:
- Pin count matches what the datasheet says for this package
- No duplicate pin numbers
- No pins are missing (compare against the datasheet's stated pin count)
- Pin names look reasonable (not garbled OCR artifacts)
Prefer “Ordering Information” / “Device Information” tables.
### 7. Validate and output
### 5. Extract absolute maximum ratings
Validate your extraction against the output schema:
Copy the **Absolute Maximum Ratings** table (not Recommended Operating Conditions):
- `parameter`, `min` / `max`, `unit`, `source_page` (1-based)
Include supply voltages, pin/input voltages, input current, temperature. Skip HBM/IEC kV ESD rows unless they are the only voltage limit. Do not invent numbers.
**ESD / TVS (`ic.protection.esd` and similar):** also from Electrical Characteristics:
- Vrwm / operating voltage as signed min/max in volts
- One row for polarity/topology as printed (`bidirectional`, …), `unit: "—"`
### 6. Assign component subtype
Pick the best dotted subtype from `EXISTING IC TAXONOMY SUBTYPES` (e.g. `ic.mcu`, `ic.power.ldo`). If none fit, propose `ic.{category}.{specific}`.
### 7. Quality checks
Before output:
- Pin count matches the package for this MPN
- No duplicate / missing pin numbers
- `layout_rules` scanned (list present; `[]` only if truly no guidance)
- Every emitted rule has a valid `kind`; every numeric `max_distance_mm` comes from the PDF text/figure
- Pin names are not OCR garbage
### 8. Validate and output
```bash
python3 /skills/extract-pintable/validate.py '<your JSON here>'
```
If validation passes, call the `save_pintable` tool with the structured result.
Do NOT write files to disk — use the tool.
If validation passes, call `save_pintable`. Do NOT write files to disk — use the tool.
skills/extract-pintable/schema.json
+24 -1
View File
@@ -56,7 +56,30 @@
},
"layout_rules": {
"type": "array",
"items": {"type": "object"}
"description": "PCB layout constraints from typical-application / PCB layout pages. Empty if none stated.",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"decoupling_proximity",
"thermal_via",
"keepout",
"length_match"
]
},
"pin": {"type": ["string", "null"]},
"cap_value_hint": {"type": ["string", "null"]},
"max_distance_mm": {"type": ["number", "null"]},
"same_layer": {"type": ["boolean", "null"]},
"min_via_count": {"type": ["integer", "null"]},
"net_class": {"type": ["string", "null"]},
"note": {"type": ["string", "null"]},
"source_page": {"type": ["integer", "null"]}
},
"required": ["kind"]
}
}
},
"required": ["component_subtype", "package_info", "pintable"]
skills/extract-pintable/validate.py
+56
View File
@@ -93,6 +93,62 @@ def validate(data: dict) -> list[str]:
kind = row.get("kind")
if kind not in kinds:
errors.append(f"layout_rules[{i}] unknown kind: {kind!r}")
continue
dist = row.get("max_distance_mm")
if dist is not None and dist is not False:
if isinstance(dist, bool):
errors.append(
f"layout_rules[{i}].max_distance_mm must be a number or null"
)
elif isinstance(dist, (int, float)):
if float(dist) <= 0:
errors.append(
f"layout_rules[{i}].max_distance_mm must be > 0"
)
else:
try:
v = float(str(dist).strip())
except (TypeError, ValueError):
errors.append(
f"layout_rules[{i}].max_distance_mm must be numeric "
f"or null (got {dist!r}) — do not invent distances; "
f"use null when the PDF only says 'close'"
)
else:
if v <= 0:
errors.append(
f"layout_rules[{i}].max_distance_mm must be > 0"
)
via = row.get("min_via_count")
if via is not None and via is not False and not isinstance(via, bool):
if isinstance(via, int):
if via <= 0:
errors.append(
f"layout_rules[{i}].min_via_count must be > 0"
)
else:
try:
iv = int(float(str(via).strip()))
except (TypeError, ValueError):
errors.append(
f"layout_rules[{i}].min_via_count must be an integer "
f"or null (got {via!r})"
)
else:
if iv <= 0:
errors.append(
f"layout_rules[{i}].min_via_count must be > 0"
)
page = row.get("source_page")
if page is not None and not isinstance(page, int):
errors.append(
f"layout_rules[{i}].source_page must be an integer or null"
)
same = row.get("same_layer")
if same is not None and not isinstance(same, bool):
errors.append(
f"layout_rules[{i}].same_layer must be a boolean or null"
)
return errors