name: ds2sf description: Datasheet → symbol + footprint + provenance JSON. Reads a chip's datasheet PDF and emits sym_create-shaped symbol JSON, footprint metadata, a field-level provenance audit trail, and an agent-to-agent result.json with stable exit codes for programmatic re-search-and-retry. Trigger words — ds2sf, datasheet to symbol, datasheet to footprint, extract symbol from datasheet, extract footprint from datasheet, datasheet pinout extract, sym extracted json, fp extracted json, datasheet sym fp, chip pin grouping, pin provenance, footprint provenance, sym_create input from datasheet, ds2sf result.json, datasheet extractor agent contract.

ds2sf — datasheet → symbol + footprint + provenance

Pipeline: read a chip-fetcher chip directory, send the datasheet PDF to Claude in two focused passes (symbol → footprint), normalize the package against the service-kicad standard library, and emit four JSON files alongside the existing chip-fetcher artifacts.

⚠ Always Opus, never Haiku

Production runs MUST use the default --model claude-opus-4-7. EEs rely on this output to wire schematics; Haiku's chip-data misreads are not acceptable in that pipeline. Concur (the cross-source consensus check) does catch most Haiku errors via 4-source consensus, but the right answer is to not produce them in the first place. Override the model only for development experiments where a follow-up Opus pass is acceptable.

When to use

• After chip-fetcher lands a chip into ~/project/chip-fetcher/library/<MPN>/.
• When you want an Adom-grouped symbol (POWER / I2C / GPIO / etc.) — the UL bundle's .kicad_sym is flat and ungrouped.
• When you need a downstream-ready sym_create input JSON.
• When you need page-level provenance to deeplink the Adom user back to the datasheet PDF page each fact came from.

Module products: pass --pdf explicitly

For module products (ESP32-WROOM, NORA, ATWINC, SARA-R5, etc.), chip-fetcher's auto-named <MPN>.pdf may be the internal SoC datasheet — which has the SoC's pinout, not the module's external castellated-pad pinout. The extractor will refuse to hallucinate (writes a result.json with status: "needs_better_pdf" and a list of candidate PDFs already on disk).

Look for the module-specific PDF in the chip-dir (<MPN>-original.pdf, <MPN>-datasheethardware-guideline.pdf, etc.) and pass it via --pdf:

ds2sf extract /home/adom/project/chip-fetcher/library/ESP32-S3-WROOM-1-N4 \
  --pdf /home/adom/project/chip-fetcher/library/ESP32-S3-WROOM-1-N4/ESP32-S3-WROOM-1-N4-original.pdf

Commands

ds2sf extract <CHIP-DIR>

Run the full pipeline against a chip directory.

Example:

ds2sf extract /home/adom/project/chip-fetcher/library/ADS1115IDGSR

ds2sf normalize <PACKAGE>

Resolve a package string against service-kicad's standard library (debug aid).

ds2sf normalize "VSSOP-10"
# OK: VSSOP-10 → Package_SO:MSOP-10_3x3mm_P0.5mm (service-kicad stdlib)

ds2sf inspect <CHIP-DIR>

Print a summary of an existing extraction without re-running anything.

ds2sf health

Probe claude CLI + service-kicad reachability.

ds2sf install

Drop this SKILL.md into ~/.claude/skills/ds2sf/.

Outputs

<chip-dir>/
  <MPN>-symbol.extracted.json        # sym_create-shaped (only on status=ok)
  <MPN>-footprint.extracted.json     # fp-metadata-shaped (only on status=ok)
  <MPN>-extraction.provenance.json   # audit trail (only on status=ok)
  <MPN>-extraction.result.json       # agent-to-agent contract (always written)
  .ds2sf-cache/                      # raw Claude responses for re-emit / debug

The provenance JSON is the audit trail. Open the file, pick a pin, follow pin_provenance[i].page → open that page in the datasheet PDF → confirm the pin name + description are visibly there. Same for footprint dimensions via dimension_provenance[i].page + figure_label.

Agent-to-agent contract

ds2sf is built so an upstream agent (chip-fetcher, automation) can call it programmatically, read the result, and decide what to do next without human input.

Exit codes

<MPN>-extraction.result.json shape

Always written. Stable schema (schema_version: "1"):

{
  "schema_version": "1",
  "status": "ok | needs_better_pdf | unrecoverable",
  "exit_code": 0 | 2 | 3,
  "mpn": "ADS1115IDGSR",
  "manufacturer": "TI",
  "datasheet_used": "/home/.../ADS1115IDGSR.pdf",
  "datasheet_sha256": "65231e81…",
  "summary": "ADS1115IDGSR — 10 pins, package VSSOP-10 …",
  "review_required": [ … merged from symbol + footprint passes … ],
  "hints": [
    { "action": "try_alternate_pdf",
      "reason": "module_external_pinout_missing",
      "candidates": ["/path/to/X-original.pdf", "/path/to/X-hardware-guidelines.pdf"] },
    { "action": "update_upstream_metadata",
      "file": "/path/to/info.json",
      "key": "package",
      "current": "VQFN-32 (5×5×0.9 mm)",
      "extracted": "VQFN-40 (7×5×0.9 mm)" },
    { "action": "use_datasheet_extracted_footprint",
      "package": "Optical LGA-16" },
    { "action": "human_review",
      "reason": "muxed_pin_protocol_select",
      "notes": "…" }
  ],
  "outputs": {
    "symbol_json": "/path/to/X-symbol.extracted.json | null",
    "footprint_json": "/path/to/X-footprint.extracted.json | null",
    "provenance_json": "/path/to/X-extraction.provenance.json | null"
  },
  "extractor_version": "0.1.0",
  "claude_model": "claude-opus-4-7"
}

Canonical review_required.reason values

Agent calling recipe

// (Pseudo-Rust for chip-fetcher's caller side.)

fn run_ds2sf(chip_dir: &Path, pdf_override: Option<&Path>) -> ResultDoc {
    let mut cmd = Command::new("ds2sf");
    cmd.arg("extract").arg(chip_dir).arg("--force").arg("--json-only");
    if let Some(p) = pdf_override { cmd.arg("--pdf").arg(p); }
    let _ = cmd.status();  // exit code mirrored in result.json
    let path = chip_dir.join(format!("{}-extraction.result.json", basename(chip_dir)));
    serde_json::from_str(&fs::read_to_string(path).unwrap()).unwrap()
}

let mut tried: HashSet<PathBuf> = HashSet::new();
let mut r = run_ds2sf(chip_dir, None);
tried.insert(r.datasheet_used.clone());

while r.status == "needs_better_pdf" {
    // Pull the first try_alternate_pdf hint we haven't already tried.
    let next = r.hints.iter()
        .filter_map(|h| if let Hint::TryAlternatePdf { candidates, .. } = h { Some(candidates) } else { None })
        .flatten()
        .find(|c| !tried.contains(*c));
    let Some(next) = next else {
        // Out of candidates — escalate to human.
        log_for_review(&r); break;
    };
    tried.insert(next.clone());
    r = run_ds2sf(chip_dir, Some(next));
}

match r.status.as_str() {
    "ok" => {
        accept(r.outputs);
        // Apply update_upstream_metadata hints (e.g. fix info.json's package).
        for h in &r.hints {
            if let Hint::UpdateUpstreamMetadata { file, key, extracted, .. } = h {
                patch_json(file, key, extracted);
            }
        }
    }
    "unrecoverable" => log_for_review(&r),
    _ => unreachable!(),
}

Caching behavior under cache-hit

If <MPN>-extraction.provenance.json already exists and --force is not passed, ds2sf skips the Claude calls entirely and exits with the cached result.json's exit code. Re-running is idempotent.