Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/datasheets

datasheets

Verified

Extract structured specifications from electronic component datasheet PDFs — pinouts, electrical characteristics, peripherals, topology, and features. Cache extractions per project for consumption by schematic and PCB analyzers. Primary consumer infrastructure for `kicad`, `emc`, `spice`, and `thermal` analyzers. Use this skill whenever the user asks to extract, verify, or read specs from a component datasheet; when analyzers need verified IC knowledge (EN pin thresholds, PG presence, USB peripheral speed); or when a review mentions datasheet coverage, extraction quality, or per-MPN specifications. Also triggers on "extract this datasheet", "what are the specs for MPN X", "verify datasheet extraction", or "check pin functions for part Y".

FileKindSize
SKILL.mdskill md11.2 KB
datasheet_types/__init__.pyscript1.9 KB
datasheet_types/base_block.pyscript6.5 KB
datasheet_types/cache_reader.pyscript12.3 KB
datasheet_types/codec.pyscript6.3 KB
datasheet_types/extraction.pyscript8.0 KB
datasheet_types/pinout.pyscript5.2 KB
datasheet_types/regulator.pyscript5.3 KB
datasheet_types/spec_value.pyscript2.4 KB
datasheet_types/trust_gating.pyscript5.0 KB
distributor_core/__init__.pyscript0 B
distributor_core/cli.pyscript2.9 KB
distributor_core/download.pyscript36.7 KB
distributor_core/inputs.pyscript9.0 KB
distributor_core/manifest.pyscript5.7 KB
distributor_core/sync.pyscript21.0 KB
distributor_core/verify.pyscript12.1 KB
examples/abm8g-106-12.000mhz-t.jsonconfig9.4 KB
examples/irlml6344.jsonconfig16.0 KB
examples/lm2596-adj.jsonconfig14.3 KB
examples/lm358.jsonconfig15.6 KB
examples/mbrs540t3g.jsonconfig12.3 KB
examples/stm32f103c8t6.jsonconfig51.1 KB
prompts/base.mdmarkdown4.5 KB
prompts/crystal.mdmarkdown8.8 KB
prompts/diode.mdmarkdown8.3 KB
prompts/mcu.mdmarkdown9.6 KB
prompts/opamp.mdmarkdown10.7 KB
prompts/pinout.mdmarkdown4.7 KB
prompts/regulator.mdmarkdown4.4 KB
prompts/scout.mdmarkdown3.5 KB
prompts/transistor.mdmarkdown12.5 KB
references/cache-layout.mdmarkdown8.4 KB
references/consumer-api.mdmarkdown10.8 KB
references/dispatch-claude-code.mdmarkdown9.4 KB
references/dispatcher-contract.mdmarkdown8.2 KB
references/extraction-pipeline.mdmarkdown1.7 KB
references/extraction-schema.mdmarkdown18.0 KB
references/field-extraction-guide.mdmarkdown14.9 KB
references/quality-scoring.mdmarkdown8.4 KB
schemas/CHANGELOG.mdmarkdown16.0 KB
schemas/base.schema.jsonconfig9.3 KB
schemas/crystal.schema.jsonconfig7.2 KB
schemas/diode.schema.jsonconfig7.9 KB
schemas/extraction.schema.jsonconfig3.7 KB
schemas/fixtures/lm2596-adj.example.jsonconfig14.3 KB
schemas/fixtures/manifest.example.jsonconfig1000 B
schemas/fixtures/minimal.example.jsonconfig2.1 KB
schemas/manifest.schema.jsonconfig3.0 KB
schemas/mcu.schema.jsonconfig12.4 KB
schemas/opamp.schema.jsonconfig9.2 KB
schemas/pinout.schema.jsonconfig5.9 KB
schemas/plan.schema.jsonconfig4.6 KB
schemas/regulator.schema.jsonconfig8.4 KB
schemas/scout.schema.jsonconfig2.9 KB
schemas/spec_value.schema.jsonconfig3.0 KB
schemas/transistor.schema.jsonconfig12.0 KB
scripts/_smoke_v14_roundtrip.pyscript8.9 KB
scripts/datasheet_extract_cache.pyscript21.2 KB
scripts/datasheet_features.pyscript17.1 KB
scripts/datasheet_page_selector.pyscript16.7 KB
scripts/datasheet_score.pyscript15.5 KB
scripts/datasheet_verify.pyscript45.6 KB
scripts/extraction_schema.pyscript1.8 KB
scripts/merge_results.pyscript13.0 KB
scripts/plan_extraction.pyscript9.5 KB
scripts/validate_extraction_result.pyscript4.0 KB
scripts/validate_sanity_vector.pyscript6.4 KB

references/consumer-api.md

View on GitHub
# Consumer API Reference

How to consume structured datasheet extractions in analyzer code. Covers the `datasheet_features.py` helper, the raw cache access functions from `datasheet_extract_cache.py`, and the skip-with-INFO pattern for detectors that require extraction data.

---

## datasheet_features.py

This module provides typed accessors that abstract cache lookup, null safety, and field path traversal.

### `get_regulator_features(mpn, *, extract_dir=None, analysis_json=None, project_dir=None) -> dict | None`

Returns a dict of regulator-relevant fields from the extraction, or `None` if no extraction is available.

`get_regulator_features` and `get_mcu_features` return `None` only when no extraction is cached for the MPN (`_load`), or when the part is not of the requested kind: topology outside `boost` / `buck` / `ldo` for the regulator helper, topology other than `mcu` for the MCU helper. They also return `None` when no project is named, and `get_mcu_features` returns `None` when only a v1.4 extraction is cached (it falls through to the legacy cache, the only one that carries its fields). Quality is **described, not gated** for these two helpers: the returned dict always carries `quality`, a dict `{score, scale, trusted, reasons}` built by `_quality_v13` (v1.3 caches, scale `0-10`) or `_quality_v14` (v1.4 caches, scale `0-100`), and callers decide. Legacy v1.3 caches (score below `MIN_SCORE`, old `EXTRACTION_VERSION`) are still returned, with `quality.trusted` false and `quality.reasons` such as `low_score (...)` or `stale_version (...)`. `get_pin_function` and `is_extraction_available` gate on `quality.trusted` for legacy caches only (see Quality Gate below).

```python
from datasheet_features import get_regulator_features

feat = get_regulator_features('TPS61023DRLR', project_dir='.')
# Returns:
# {
#     'topology': 'boost',
#     'has_pg': False,           # None if unknown
#     'has_soft_start': True,    # None if unknown
#     'iss_time_us': 12.5,       # None if unknown
#     'en_v_ih_max': 0.96,       # None if not in extraction
#     'en_v_il_min': 0.4,        # None if not in extraction
#     'vin_pin': '2',            # Pin number (str) or None
#     'vout_pin': '3',           # Pin number (str) or None
#     'en_pin': '1',             # Pin number (str) or None
#     'pg_pin': None,            # Pin number (str) or None
#     'quality': {'score': 8.4, 'scale': '0-10', 'trusted': True, 'reasons': []},
# }
# or None if no extraction exists for this MPN
```

Returned dict fields:

| Field | Type | Description |
|-------|------|-------------|
| `topology` | `'boost' \| 'buck' \| 'ldo'` | Circuit topology |
| `has_pg` | `bool \| None` | Part has a power-good output pin |
| `has_soft_start` | `bool \| None` | Integrated soft-start circuit |
| `iss_time_us` | `float \| None` | Soft-start time in microseconds |
| `en_v_ih_max` | `float \| None` | EN pin logic-high threshold (V) |
| `en_v_il_min` | `float \| None` | EN pin logic-low threshold (V) |
| `vin_pin` | `str \| None` | Pin number of VIN pin |
| `vout_pin` | `str \| None` | Pin number of VOUT pin |
| `en_pin` | `str \| None` | Pin number of EN pin |
| `pg_pin` | `str \| None` | Pin number of PG pin |
| `quality` | `dict` | `{score, scale, trusted, reasons}`; always present |

### `get_mcu_features(mpn, *, extract_dir=None, analysis_json=None, project_dir=None) -> dict | None`

Returns MCU-relevant fields, or `None` if no extraction is available.

Returns `None` when:
- No extraction is cached for the MPN
- Extraction topology is not `'mcu'`
- No project is named (no `project_dir`, `extract_dir` or `analysis_json`)
- Only a v1.4 extraction is cached

```python
from datasheet_features import get_mcu_features

mcu = get_mcu_features('ESP32-S3', project_dir='.')
# Returns:
# {
#     'usb_speed': 'FS',          # 'FS' | 'HS' | 'SS' | None
#     'has_native_usb_phy': True, # None if unknown
#     'usb_series_r_required': True,
#     'quality': {'score': 8.4, 'scale': '0-10', 'trusted': True, 'reasons': []},
# }
# or None if no extraction exists
```

Returned dict fields:

| Field | Type | Description |
|-------|------|-------------|
| `usb_speed` | `'FS' \| 'HS' \| 'SS' \| None` | USB device speed |
| `has_native_usb_phy` | `bool \| None` | Native USB PHY present |
| `usb_series_r_required` | `bool \| None` | Series termination resistors required |
| `quality` | `dict` | `{score, scale, trusted, reasons}`; always present |

### `get_pin_function(mpn, pin_identifier, *, extract_dir=None, analysis_json=None, project_dir=None) -> str | None`

Returns the functional category of a pin, or `None` if not found or extraction unavailable.

`pin_identifier` matches against `pins[].number` (exact match, string) or `pins[].name` (case-insensitive).

```python
from datasheet_features import get_pin_function

fn = get_pin_function('TPS61023DRLR', 'EN', project_dir='.')
# Returns: 'EN' (the pin's function field)
# or None if extraction missing or pin not found
```

Possible return values: `'VIN'`, `'VOUT'`, `'EN'`, `'PG'`, `'SW'`, `'FB'`, `'GND'`, `'IO'`, `'CLK'`, `'RESET'`, `'OTHER'`, or `None`.

### `is_extraction_available(mpn, *, extract_dir=None, analysis_json=None, project_dir=None) -> bool`

Returns `True` iff a v1.4 extraction exists for the MPN, or a v1.3 extraction exists whose `quality.trusted` is true (not stale, score at least `MIN_SCORE`).

```python
from datasheet_features import is_extraction_available

if is_extraction_available('TPS61023DRLR', project_dir='.'):
    # Safe to call get_regulator_features()
    pass
```

---

## None Contract

The contract for all helper functions: individual fields within a returned dict may be `None`, distinct from `False` or `0`.

| Value | Meaning | Detector action |
|-------|---------|----------------|
| `None` (whole return) | No extraction cached, no project named, or the part is not the requested kind (`get_pin_function`: also an untrusted v1.3 extraction or unknown pin) | Skip the check; emit INFO |
| `None` (field within dict) | Datasheet didn't specify this field | Treat as unknown; do not fire checks based on this field |
| `False` | Datasheet explicitly says feature is absent | Fire relevant checks if configured |
| `0` / `0.0` | Datasheet specifies zero | Treat as numeric zero |

Detectors must distinguish `None` (unknown) from `False` (explicitly no). Example: `has_pg=None` means unknown; `has_pg=False` means confirmed absent.

---

## Skip Pattern for Detectors

When a detector needs extraction data and the helper function returns `None` (whole function return), emit an INFO-level finding and return — do not fire the rule.

```python
feat = get_regulator_features(mpn, project_dir=ctx.project_dir)
if feat is None:
    findings.append({
        "severity": "info",
        "rule_id": "SS-004",
        "summary": (
            f"Check SS-004 skipped for {ref}: no datasheet extraction for {mpn}. "
            f"Download the datasheet and run the datasheets extraction pipeline."
        ),
        "detector": "audit_soft_start",
    })
    return findings

# feat may still be untrusted: check feat['quality']['trusted'] before relying on its fields
if feat['has_soft_start'] is None:
    # Field not in extraction; skip this particular sub-check
    pass
elif feat['has_soft_start']:
    # Feature present; run the check
    pass
```

Format for the skip message:
```
Check <rule_id> skipped for <ref>: no datasheet extraction for <mpn>. Download the datasheet and run the datasheets extraction pipeline.
```

Do not emit a warning or error for a missing extraction — INFO is the correct severity. The extraction is optional; its absence means the check cannot run, not that there is a design problem.

---

## Direct Cache Access

For cases where the helper functions do not cover the needed field, use the cache functions directly.

### `get_cached_extraction(extract_dir, mpn) -> dict | None`

Returns the full extraction dict, or `None` if not cached.

```python
from datasheet_extract_cache import get_cached_extraction, resolve_extract_dir

extract_dir = resolve_extract_dir(analysis_json=analysis)
extraction = get_cached_extraction(extract_dir, mpn) if extract_dir else None
if extraction is None:
    # no cached data — skip checks that need it
    pass
```

### `resolve_extract_dir(analysis_json=None, project_dir=None, override_dir=None) -> Path | None`

Resolves the `datasheets/extracted/` directory for a project:

1. If `override_dir` is set, use it directly.
2. If `project_dir` is set, use `<project_dir>/datasheets/extracted/`.
3. If `analysis_json` is provided, use the directory of its `"file"` field, else of its first `inputs.source_files` entry.
4. Otherwise return `None`: there is no cache, and the helpers return `None`. There is no shared temp-directory fallback.

In cases 2 and 3 the result is also `None` (with one stderr warning) when the project's `datasheets/` or `datasheets/extracted/` folder is a symlink (`cache_reader.safe_extract_dir`). An `override_dir` is used as given, link or not.

```python
extract_dir = resolve_extract_dir(project_dir="/path/to/project")
```

---

## Resolving extract_dir in Detectors

Detectors called from `analyze_schematic.py` receive an `AnalysisContext` with `ctx.project_dir` (the schematic's folder) and `ctx.cache_dir` (the `datasheets/extracted/` folder used by `lookup()`, or `None`). Pass `project_dir=ctx.project_dir` to the helpers in this file; they return `None` when the project has no cache.

```python
# In a detector
feat = get_regulator_features(mpn, project_dir=ctx.project_dir)
```

If the project has no `datasheets/extracted/` folder, skip silently (no INFO finding) — this is the normal state for projects that have not run the extraction pipeline.

---

## Quality Gate

Quality handling differs by helper (`datasheet_features.py`):

- `get_regulator_features()` and `get_mcu_features()` **describe** quality and do not gate. Any cached extraction of the right kind is returned with `quality = {score, scale, trusted, reasons}`. A detector that needs verified data checks `quality['trusted']` itself and may downgrade confidence or skip.
- `get_pin_function()` and `is_extraction_available()` **gate** on the v1.3 path: an extraction with `quality['trusted']` false (stale `extraction_version` below `EXTRACTION_VERSION`, or `extraction_score` below `MIN_SCORE`, 6.0) yields `None` / `False`. The v1.4 path for these two helpers is not score-gated.

`None` from `get_regulator_features()` or `get_mcu_features()` therefore means "no cached extraction of that kind", not "low quality". For direct cache access, apply the gate explicitly when you need one:

```python
from datasheet_extract_cache import get_cached_extraction, EXTRACTION_VERSION, MIN_SCORE

ext = get_cached_extraction(extract_dir, mpn)
if not ext:
    return []  # skip

meta = ext.get('extraction_metadata') or {}
if (meta.get('extraction_version') or 0) < EXTRACTION_VERSION:
    return []  # stale, skip

if (meta.get('extraction_score') or 0) < MIN_SCORE:
    return []  # low quality, skip
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall