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

scripts/datasheet_score.py

View on GitHub
"""
Quality scoring for structured datasheet extractions.

Evaluates an extraction JSON against a completeness rubric across five
dimensions: pin coverage, voltage ratings, operating conditions, application
info, and SPICE-relevant specs. Returns a weighted score 0.0-10.0 with
per-dimension breakdown and a list of specific issues found.

The scoring is deterministic — same input always produces same score. It
runs after Claude performs the extraction and tells Claude (and the cache
manager) whether the extraction is good enough or needs a retry.
"""


# ---------------------------------------------------------------------------
# Category-specific electrical characteristic requirements
# ---------------------------------------------------------------------------

_ECHAR_REQUIREMENTS = {
    # category: (required_fields, nice_to_have_fields)
    "operational_amplifier": (
        ["gbw_hz", "slew_vus"],
        ["vos_mv", "aol_db", "rin_ohms"],
    ),
    "comparator": (
        ["prop_delay_ns"],
        ["vos_mv", "aol_db"],
    ),
    "linear_regulator": (
        ["vref_v", "quiescent_current_ua"],
        ["dropout_mv", "output_current_max_ma"],
    ),
    "switching_regulator": (
        ["vref_v", "switching_frequency_khz"],
        ["quiescent_current_ua", "output_current_max_ma"],
    ),
    "voltage_reference": (
        ["vref_v", "vref_accuracy_pct"],
        ["temp_coefficient_ppmk"],
    ),
    "microcontroller": (
        [],  # MCUs have diverse e-chars, no universal required set
        ["quiescent_current_ua", "io_voltage_max"],
    ),
    "esd_protection": (
        ["clamping_voltage_v"],
        ["leakage_current_na", "capacitance_pf"],
    ),
}

# Fallback for categories not listed above
_ECHAR_DEFAULT = ([], [])


# ---------------------------------------------------------------------------
# SPICE spec requirements per category
# ---------------------------------------------------------------------------

_SPICE_REQUIREMENTS = {
    "operational_amplifier": ["gbw_hz"],
    "comparator": [],  # comparators rarely need SPICE behavioral models
    "linear_regulator": ["vref", "dropout_mv"],
    "switching_regulator": ["vref"],
    "voltage_reference": ["vref"],
}


# ---------------------------------------------------------------------------
# Scoring functions
# ---------------------------------------------------------------------------

def _score_pin_coverage(extraction, expected_pin_count=None):
    """Score pin coverage (0-10).

    10.0 = all pins present with name, type, and at least one electrical spec.
    Deductions: -2 per missing pin, -1 per pin with name only (no specs).
    0.0 if fewer than 50% of expected pins documented.
    """
    pins = extraction.get("pins", [])
    if not pins:
        return 0.0, ["No pins documented"]

    num_pins = len(pins)
    expected = expected_pin_count or num_pins  # if no expected count, use what we have

    # Check if we have enough pins
    if expected > 0 and num_pins < expected * 0.5:
        return 0.0, [f"Only {num_pins}/{expected} pins documented (<50%)"]

    issues = []
    pins_with_specs = 0
    pins_with_name_only = 0

    for pin in pins:
        has_name = bool(pin.get("name"))
        has_electrical = any([
            pin.get("voltage_abs_max") is not None,
            pin.get("voltage_operating_min") is not None,
            pin.get("voltage_operating_max") is not None,
            pin.get("current_max_ma") is not None,
            pin.get("threshold_high_v") is not None,
            pin.get("threshold_low_v") is not None,
        ])
        has_description = bool(pin.get("description"))
        has_required = bool(pin.get("required_external"))

        if has_name and (has_electrical or has_description or has_required):
            pins_with_specs += 1
        elif has_name:
            pins_with_name_only += 1
            issues.append(f"Pin {pin.get('number', '?')} ({pin.get('name', '?')}): name only, no specs")
        else:
            issues.append(f"Pin {pin.get('number', '?')}: missing name")

    # Calculate score
    if expected == 0:
        return 10.0, []

    missing = max(0, expected - num_pins)
    score = 10.0
    score -= missing * 2.0  # -2 per missing pin
    score -= pins_with_name_only * 1.0  # -1 per name-only pin

    if missing > 0:
        issues.insert(0, f"{missing} pin(s) missing from extraction")

    return max(0.0, min(10.0, score)), issues[:5]  # cap issues for readability


def _score_voltage_ratings(extraction):
    """Score voltage/thermal ratings completeness (0-10).

    10.0 = abs max has vin_max + junction_temp, operating has vin range + temp range.
    """
    abs_max = extraction.get("absolute_maximum_ratings", {})
    operating = extraction.get("recommended_operating_conditions", {})
    issues = []
    score = 10.0

    # Absolute maximum ratings
    if not abs_max:
        score -= 3.0
        issues.append("No absolute maximum ratings")
    else:
        if abs_max.get("junction_temp_max_c") is None:
            score -= 1.0
            issues.append("Missing junction temperature max")
        # Check for at least one voltage abs max
        voltage_keys = [k for k in abs_max if k.endswith("_max_v") and abs_max[k] is not None]
        if not voltage_keys:
            score -= 2.0
            issues.append("No voltage absolute maximum ratings")

    # Recommended operating conditions
    if not operating:
        score -= 3.0
        issues.append("No recommended operating conditions")
    else:
        if operating.get("vin_min_v") is None or operating.get("vin_max_v") is None:
            score -= 1.5
            issues.append("Missing input voltage operating range")
        if operating.get("temp_min_c") is None or operating.get("temp_max_c") is None:
            score -= 1.0
            issues.append("Missing operating temperature range")

    return max(0.0, min(10.0, score)), issues


def _score_application_info(extraction):
    """Score application circuit information (0-10).

    10.0 = has topology + 2+ component recommendations + formula/notes.
    """
    app = extraction.get("application_circuit", {})
    issues = []
    score = 10.0

    if not app:
        return 0.0, ["No application circuit information"]

    if not app.get("topology"):
        score -= 2.0
        issues.append("Missing circuit topology")

    # Count component recommendations
    rec_fields = [
        "inductor_recommended", "input_cap_recommended", "output_cap_recommended",
        "feedback_resistor_top_ohm", "feedback_resistor_bottom_ohm",
        "compensation_cap", "bootstrap_cap", "decoupling_cap",
    ]
    recs = sum(1 for f in rec_fields if app.get(f))
    # Also count any key ending in _recommended
    recs += sum(1 for k, v in app.items()
                if k.endswith("_recommended") and k not in rec_fields and v)

    if recs == 0:
        score -= 3.0
        issues.append("No component recommendations")
    elif recs == 1:
        score -= 1.5
        issues.append("Only 1 component recommendation (expect 2+)")

    if not app.get("vout_formula") and not app.get("notes"):
        score -= 2.0
        issues.append("No formula or application notes")
    elif not app.get("notes"):
        score -= 1.0
        issues.append("No layout/application notes")

    return max(0.0, min(10.0, score)), issues


def _score_electrical_chars(extraction):
    """Score electrical characteristics (0-10), category-dependent.

    Uses category-specific required/nice-to-have field lists.
    """
    category = extraction.get("category", "")
    echars = extraction.get("electrical_characteristics", {})
    issues = []

    required, nice = _ECHAR_REQUIREMENTS.get(category, _ECHAR_DEFAULT)

    if not echars:
        if required:
            return 0.0, [f"No electrical characteristics (need {', '.join(required)})"]
        return 5.0, ["No electrical characteristics (none strictly required for this category)"]

    score = 10.0

    # Check required fields
    for field in required:
        if echars.get(field) is None:
            score -= 3.0
            issues.append(f"Missing required: {field}")

    # Check nice-to-have fields
    for field in nice:
        if echars.get(field) is None:
            score -= 1.0
            issues.append(f"Missing optional: {field}")

    # Bonus: if category has no requirements but we got some data, that's good
    if not required and not nice:
        populated = sum(1 for v in echars.values() if v is not None)
        if populated >= 3:
            score = 10.0
        elif populated >= 1:
            score = 7.0
        else:
            score = 5.0

    return max(0.0, min(10.0, score)), issues[:5]


def _score_spice_specs(extraction):
    """Score SPICE-relevant specs (0-10).

    10.0 = enough fields for the component category's behavioral model.
    """
    category = extraction.get("category", "")
    spice = extraction.get("spice_specs", {})
    issues = []

    if not spice:
        # Check if we can derive from electrical_characteristics
        echars = extraction.get("electrical_characteristics", {})
        if echars:
            # Some specs can be pulled from e-chars
            return 5.0, ["No spice_specs section (could derive from electrical_characteristics)"]
        return 0.0, ["No SPICE-relevant specs"]

    required = _SPICE_REQUIREMENTS.get(category, [])
    score = 10.0

    for field in required:
        if spice.get(field) is None:
            score -= 4.0
            issues.append(f"Missing SPICE spec: {field}")

    # Count populated fields
    populated = sum(1 for v in spice.values() if v is not None)
    if populated == 0:
        return 0.0, ["spice_specs section is empty"]
    elif populated <= 2 and not required:
        score = min(score, 6.0)

    return max(0.0, min(10.0, score)), issues


# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------

def score_extraction(extraction, expected_pin_count=None):
    """Score a datasheet extraction for completeness.

    Evaluates across five weighted dimensions and returns a total score
    (0.0-10.0) along with per-dimension scores and specific issues.

    Args:
        extraction: Parsed extraction JSON dict
        expected_pin_count: If known (from schematic), used for pin coverage

    Returns:
        {
            "total": 8.2,
            "pin_coverage": 9.0,
            "voltage_ratings": 8.5,
            "application_info": 7.0,
            "electrical_characteristics": 8.0,
            "spice_specs": 8.5,
            "issues": ["Missing abs max for SW pin", ...],
            "sufficient": True  # True if total >= 6.0
        }
    """
    pin_score, pin_issues = _score_pin_coverage(extraction, expected_pin_count)
    volt_score, volt_issues = _score_voltage_ratings(extraction)
    app_score, app_issues = _score_application_info(extraction)
    echar_score, echar_issues = _score_electrical_chars(extraction)
    spice_score, spice_issues = _score_spice_specs(extraction)

    # Weighted average (weights sum to 1.0)
    total = (
        pin_score * 0.35 +
        volt_score * 0.25 +
        app_score * 0.20 +
        echar_score * 0.10 +
        spice_score * 0.10
    )

    all_issues = pin_issues + volt_issues + app_issues + echar_issues + spice_issues

    return {
        "total": round(total, 1),
        "pin_coverage": round(pin_score, 1),
        "voltage_ratings": round(volt_score, 1),
        "application_info": round(app_score, 1),
        "electrical_characteristics": round(echar_score, 1),
        "spice_specs": round(spice_score, 1),
        "issues": all_issues,
        "sufficient": total >= 6.0,
    }


# ---------------------------------------------------------------------------
# v1.4 rubric extension
# ---------------------------------------------------------------------------

# Per-pin fields scored by population (1 point each, max 4 pts/pin)
_PIN_FIELDS = ("name", "type", "power_domain", "evidence")

# Base block "fully populated" reference field set
_BASE_FIELD_REFS = {
    "package":               ["code", "pin_count"],
    "thermal":               ["theta_ja"],
    "absolute_max":          ["VIN_max", "TJ_max"],
    "recommended_operating": ["VIN", "TA"],
    "esd":                   ["HBM"],
}

# Per-category required+nice-to-have fields
_CATEGORY_FIELD_REQS = {
    "regulator": {
        "required": ("topology", "vin_range", "vout_range", "iout_max"),
        "nice":     ("reference_voltage", "switching_freq", "cin_min", "cout_min", "enable_pin"),
    },
    # 3b: mcu, opamp, transistor, diode, crystal
}


def _populated(value) -> bool:
    if value is None:
        return False
    if isinstance(value, (list, dict)) and not value:
        return False
    return True


def _pinout_completeness(extraction: dict) -> float:
    pinout = ((extraction.get("base") or {}).get("pinout")) or []
    if not isinstance(pinout, list):
        return 0.0  # sentinel ({_extraction_failed: true}) or malformed pinout block
    if not pinout:
        return 0.0
    pts_per_pin = len(_PIN_FIELDS)
    earned = 0
    total = pts_per_pin * len(pinout)
    for p in pinout:
        for f in _PIN_FIELDS:
            if _populated(p.get(f)):
                earned += 1
    return earned / total if total else 0.0


def _base_completeness(extraction: dict) -> float:
    base = extraction.get("base") or {}
    if not base:
        return 0.0
    if isinstance(base, dict) and base.get("_extraction_failed"):
        return 0.0  # base block extraction failed (post-retry sentinel)
    earned = 0
    total = sum(len(v) for v in _BASE_FIELD_REFS.values())
    for block, keys in _BASE_FIELD_REFS.items():
        b = base.get(block) or {}
        if not isinstance(b, dict):
            continue
        for k in keys:
            if _populated(b.get(k)):
                earned += 1
    return earned / total if total else 0.0


def _category_extension_completeness(extraction: dict) -> float:
    cats = extraction.get("categories") or []
    if not cats:
        return 0.0
    fractions = []
    for cat in cats:
        payload = extraction.get(cat)
        if not isinstance(payload, dict) or payload.get("_extraction_failed"):
            fractions.append(0.0)
            continue
        spec = _CATEGORY_FIELD_REQS.get(cat)
        if not spec:
            fractions.append(1.0)  # unknown category — full credit (3b will populate)
            continue
        req = spec["required"]
        nice = spec["nice"]
        req_score = sum(1 for f in req if _populated(payload.get(f))) / len(req) if req else 1.0
        nice_score = sum(1 for f in nice if _populated(payload.get(f))) / len(nice) if nice else 1.0
        fractions.append(0.7 * req_score + 0.3 * nice_score)
    return sum(fractions) / len(fractions) if fractions else 0.0


def score_v14_extraction(extraction: dict) -> dict:
    """Quality score (0-100) for a v1.4 extraction JSON.

    Weighted dimensions:
      pinout_completeness            20%
      base_completeness              25%
      category_extension_completeness 25%
      reserved                       30%   (always full credit)
    """
    dims = {
        "pinout_completeness": _pinout_completeness(extraction),
        "base_completeness": _base_completeness(extraction),
        "category_extension_completeness": _category_extension_completeness(extraction),
        "reserved_v15": 1.0,
    }
    weights = {
        "pinout_completeness": 0.20,
        "base_completeness": 0.25,
        "category_extension_completeness": 0.25,
        "reserved_v15": 0.30,
    }
    weighted = sum(dims[k] * weights[k] for k in dims)
    score = int(round(weighted * 100))
    return {"score": score, "dimensions": dims, "weights": weights}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall