ecadlib 0.3.0__tar.gz → 0.3.1__tar.gz

{ecadlib-0.3.0 → ecadlib-0.3.1}/CHANGELOG.md

@@ -7,6 +7,39 @@ a minor release may change command-line options and file formats.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-17
+
+### Added
+
+- Altium builds the libraries itself (`ecadlib/altium_native.py`, docs/altium-native.md): every `.PcbLib` / `.SchLib` ecadlib writes gets a `.ecadbuild` recipe, and a DelphiScript (`ecadlib_build.pas`) rebuilds them inside Altium with its own object API; `ecadlib altium-native write|compare` and a *Rebuild with Altium* step in `altium-pkg` (`--no-native-build` to skip). `compare` reads Altium's result back pad by pad and pin by pin.
+- The ecadlib menu in Altium lets Altium build the library files itself before it reinstalls the library: each job copies the parts' build recipes into the library folder and writes `ecadlib_build.txt`, and the menu calls `BuildLibraries` (`ecadlib_build.pas`, now part of the menu's script project). The dialog says when a library failed to build. `native_build=0` in `ecadlib_menu.ini` turns it off.
+- Altium footprints carry the designator on the assembly drawing too: KiCad's `${REFERENCE}` on F.Fab becomes a `.Designator` on Mechanical 13 (the `[layers] assembly` layer), and footprints without one get it centred on the body. `ecadlib parity` and the footprint check compare it between KiCad and Altium (#37).
+- Edits made in Altium are kept: each library ecadlib copies into a library folder gets a `.ecadstate` (the hash of ecadlib's file and of the file Altium built from it). A library someone changed in Altium afterwards is no longer rebuilt by the native build or replaced by `dblib-sync` / `altium-pkg`; they report it instead (`dblib-sync --overwrite-edits`, `altium-native write --rebuild-all` replace it). Libraries Altium already built and ecadlib has not changed are not rebuilt on every run.
+- `ecadlib fp-edit PLAN --part P show|rename OLD=NEW|same-net A,B|undo`: fix a held part's datasheet pad table by hand, e.g. a connector whose pads are named 1+ / 1- or T / R / S (a footprint still needs a pad 1 or A1, so a person picks it). The edit is kept in `footprint_edits.json` next to the plan, applied whenever the librarian builds the part, and noted on the part with who made it. A part held because its datasheet pad table failed the check now says which check failed and what to do (no pad 1: rename a pad with `fp-edit`; pads of two nets overlap: `same-net` if they are one net, else pick a footprint), instead of "there is no footprint yet".
+- `ecadlib sources-check` and a weekly `sources-canary` workflow: checks the unofficial EasyEDA / JLCPCB endpoints against known parts.
+
+### Changed
+
+- Pads on one net may overlap in a datasheet pad table: pads whose pins share a name in the pin table (VIN on pins 1, 2 and the paddle) are put in `same_net` automatically (NC / DNC pins never are). An exposed pad listed twice at the same place with another size (for its thermal vias) is one pad, not a misread; an exact copy is still an error. The accuracy gate's baseline moves to 328/331 (qfn-DAC60504).
+- Official part APIs first: the default provider order is Nexar, DigiKey, Mouser, then the unofficial JLCPCB search and EasyEDA. Nexar / DigiKey / Mouser answers now give the LCSC number and datasheet link. `[providers] unofficial = false` turns the unofficial endpoints off completely.
+
+- Altium (Altium 365 first) and KiCad are the supported targets. The Fusion Electronics / EAGLE and EasyEDA Pro exports are marked experimental in the README and `ecadlib -h`: they keep working but get no new features and may be removed later.
+
+### Fixed
+
+- BOM intake: `C1~C4` designator ranges are counted; European decimal quantities are not multiplied by ten; one cp1252 byte no longer garbles a UTF-8 CSV; `DNP` / `DNF` in the Value or MPN cell marks the line; a quantity-only footer row is not a part; an MPN that Excel turned into scientific notation is flagged.
+- DbLib table: parts go to the right table (LCSC long descriptions, `easyeda:C7593` is an LCSC number, an IC package outranks the description words, menu parts follow their source).
+- Altium: variants per channel and part, variant alternates by Design Item ID, the encoding of a DbLib Altium saved is kept, prune removes the STEP files ecadlib wrote, sheet name case, menu jobs and pin numbers; the native build keeps recipe footprint names as stored and keeps a library when a STEP file is missing.
+- KiCad export: re-export touches nothing unchanged and never loses hand edits; Altium keep-outs and non-copper regions are not written as copper; Bottom Paste / Bottom Solder and fill rotation are kept; KiCad name clashes are reported; a database row never points at another part's symbol.
+- 3D models: the STEP model is turned to the footprint's pads, and more EasyEDA / LCSC package names get the right body.
+- House style: `style learn` needs coverage before a setting is high and does not write low settings; `power_side = "left"` puts a lone ground at the bottom.
+- Standard parts refuse land variants, exposed-pad SOTs and contradicting size codes.
+- The approval gate works under house parameter names, and placeholder MPNs are handled.
+- Models: the feedback turn is capped, API keys are redacted, unit repair is strict, configured key names are used.
+- Altium: DbLib table names Altium's database driver can open, install scripts written in cp1252, and a warning for Unicode pin names.
+- Team server: no self-approval through the plan approval route, and an odd `sign_as` is a plain 400.
+- Security: no API key in network error messages, framing refused in local mode, a deeply nested JSON body is a plain 400.
+
 ## [0.3.0] - 2026-10-17
 
 ### Added
@@ -183,7 +216,8 @@ a minor release may change command-line options and file formats.
 - Initial prototypes: IPC-7351B footprint generator driven by `package_schema.json`, BOM triage
   against local KiCad libraries and public part sources, and Altium Database Library (DbLib) export.
 
-[Unreleased]: https://github.com/oliBrowne/PCBLIVINGLIBRARY/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/oliBrowne/PCBLIVINGLIBRARY/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/oliBrowne/PCBLIVINGLIBRARY/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/oliBrowne/PCBLIVINGLIBRARY/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/oliBrowne/PCBLIVINGLIBRARY/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/oliBrowne/PCBLIVINGLIBRARY/releases/tag/v0.1.0

{ecadlib-0.3.0 → ecadlib-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecadlib
-Version: 0.3.0
+Version: 0.3.1
 Summary: AI-assisted living ECAD component library: BOM triage, IPC-7351B footprints, Altium and KiCad export
 Author: oliver browne
 License-Expression: MIT
@@ -52,13 +52,38 @@ Requires-Dist: pillow; extra == "dev"
 Requires-Dist: tomli; extra == "dev"
 Dynamic: license-file
 
-# ecad-librarian: "AI living library" prototypes
-
-These are small Python prototypes for an open-source tool that manages ECAD components for KiCad and Altium. The design has three parts:
-
-1. An LLM reads a datasheet mechanical drawing and fills `ecadlib/package_schema.json`.
-2. A deterministic generator turns that JSON into an IPC-7351B land pattern.
-3. A triage step works out which BOM lines already exist locally, which can be pulled from a public source, and which need a generated footprint.
+# ecadlib: a librarian for your parts
+
+ecadlib keeps your component library alive. Give it a BOM and it finds every symbol, footprint and 3D model you are
+missing, draws the ones nobody has from the datasheet, makes them match the rest of your library, holds anything in
+doubt for a person to sign off, and releases the rest to **Altium 365** or **KiCad**.
+
+* **BOM in.** Altium BOMs and ActiveBOMs, KiCad BOMs and schematics, or a hand-made CSV/XLSX. Each line comes back as
+  already in your library, available from a source, needs a footprint, or DNP.
+* **Official sources first.** Nexar, DigiKey and Mouser identify the part; symbols and footprints come from your own
+  libraries and the official KiCad libraries before anything else. EasyEDA/LCSC is an unofficial source, used after
+  those, and one setting (`[providers] unofficial = false`) turns it off.
+* **Drawn from the datasheet when nobody has it.** A datasheet reader fills a package description and a deterministic
+  IPC-7351B generator draws the land pattern. It works with Claude by default or the model you choose; you bring the
+  API key.
+* **Your house style.** `ecadlib style learn` reads your existing libraries and new parts follow the same naming,
+  descriptions, value formats and parameters.
+* **Review hold.** A release check runs on every part. Anything that fails it, or still needs a person, is held back
+  from Altium 365 until someone signs it off.
+* **Altium 365 release.** Parts go to your Altium 365 workspace, or out as `.SchLib`/`.PcbLib`, a database library
+  and KiCad libraries, from one plan.
+
+Install it with `pip install ecadlib` (v0.3.1, Python 3.10+), or on Windows run the installer from the
+[Releases page](https://github.com/oliBrowne/PCBLIVINGLIBRARY/releases). It is free and open source under the MIT
+licence. Website: [pcblivinglibrary.vercel.app](https://pcblivinglibrary.vercel.app).
+
+**Supported tools:** Altium (Altium 365 first) and KiCad are the supported targets: they get the testing, the
+benchmarks and the fixes. The Fusion Electronics / EAGLE and EasyEDA Pro exports (section 11b) still work but are
+**experimental**: kept as they are, not a focus, and they may be removed.
+
+**Where it's going:** [docs/PRODUCT_SPEC.md](docs/PRODUCT_SPEC.md) says who ecadlib is for, what it must do and how
+success is measured; [ROADMAP.md](ROADMAP.md) lists what has shipped and the next milestones (v0.3.1, v0.4.0, v0.5.0)
+with their dates.
 
 ## Start here (no terminal needed)
 
@@ -71,7 +96,7 @@ who use the command line or work on ecadlib itself (section 38 covers how the in
 ## Quick start
 
 ```
-pip install -e .                 # from this checkout (Python 3.10+); `pip install ecadlib` once a release is on PyPI
+pip install ecadlib              # Python 3.10+ (or `pip install -e .` from this checkout)
 ecadlib demo                     # about a second, offline, no API keys: a small library in ./ecadlib-demo
 ecadlib init                     # a few questions -> ecadlib.toml, then a setup check and the next commands
 ecadlib librarian my_bom.csv -o ecadlib_workspace/librarian/my_bom   # fill every missing part; `ecadlib status` shows it
@@ -100,7 +125,7 @@ See section 32 for the first-run commands in detail.
 Install it with pip (Python 3.10 or later):
 
 ```
-pip install ecadlib                 # once a release is on PyPI (see Releases below)
+pip install ecadlib                 # from PyPI
 pip install "ecadlib[pdf]"          # pypdf trims datasheets to --pages
 pip install -e ".[dev]"             # from a checkout: editable, plus everything the test suite uses
 ```
@@ -149,7 +174,7 @@ That gives you a single `ecadlib` command (`python -m ecadlib` works too). There
    ```
 
    Its tools are `workspace_info`, `triage_bom` (with `summary_only` for large BOMs), `preview_footprint`, `approve_footprint`, `librarian_run` (fill every missing part, then the release check), `release_check` (with `allow` for parts a person has signed off), `held_parts`, `part_candidates` and `choose_part` (fix a held part), `approval_status` and `approve_part` (sign-off; `user` is required, the agent must pass the person's own name), `find_duplicates` (with `merge`), `build_altium_models`, `export_altium_dblib`, `altium365_plan`, `altium365_push` (dry run unless `dry_run` is false; held parts are never pushed), `sim_models` (SPICE/IBIS models; `attach` writes them) and `list_example_specs`.
-3. **CLI**, for scripts and CI: `ecadlib triage`, `ecadlib footprint`, `ecadlib check`, `ecadlib footprint-bench`, `ecadlib dblib`, `ecadlib dblib-sync`, `ecadlib altium-lib`, `ecadlib altium365`, `ecadlib kicad-export` (the library as KiCad files, section 11), `ecadlib eagle-export` and `ecadlib easyeda-export` (Fusion Electronics / EAGLE and EasyEDA Pro, section 11b), `ecadlib resolve`, `ecadlib approve`, `ecadlib dedupe`, `ecadlib sourcing`, `ecadlib step-gen`, `ecadlib upkeep` (section 15), `ecadlib a365`, `ecadlib project`, `ecadlib where-used` and `ecadlib sim-models` (section 17), `ecadlib init` and `ecadlib rules` (section 18), `ecadlib demo` (section 32), `ecadlib kicad-pcm` and `ecadlib altium-pkg` (section 31), `ecadlib ai` (section 33), `ecadlib symbol` (section 19), `ecadlib datasheet`, `ecadlib team`, `ecadlib agent` (the library agent, section 20), `ecadlib agent-watch` (21), `ecadlib queue` (22), `ecadlib visual-check` (23), `ecadlib migrate` and `ecadlib rebuild` (35). Run `ecadlib <command> -h` for options. Each is described below; the older `python3 -m ecadlib.<module>` form still works.
+3. **CLI**, for scripts and CI: `ecadlib triage`, `ecadlib footprint`, `ecadlib check`, `ecadlib footprint-bench`, `ecadlib dblib`, `ecadlib dblib-sync`, `ecadlib altium-lib`, `ecadlib altium365`, `ecadlib kicad-export` (the library as KiCad files, section 11), `ecadlib eagle-export` and `ecadlib easyeda-export` (Fusion Electronics / EAGLE and EasyEDA Pro, experimental, section 11b), `ecadlib resolve`, `ecadlib approve`, `ecadlib dedupe`, `ecadlib sourcing`, `ecadlib step-gen`, `ecadlib upkeep` (section 15), `ecadlib a365`, `ecadlib project`, `ecadlib where-used` and `ecadlib sim-models` (section 17), `ecadlib init` and `ecadlib rules` (section 18), `ecadlib demo` (section 32), `ecadlib kicad-pcm` and `ecadlib altium-pkg` (section 31), `ecadlib ai` (section 33), `ecadlib symbol` (section 19), `ecadlib datasheet`, `ecadlib team`, `ecadlib agent` (the library agent, section 20), `ecadlib agent-watch` (21), `ecadlib queue` (22), `ecadlib visual-check` (23), `ecadlib migrate` and `ecadlib rebuild` (35). Run `ecadlib <command> -h` for options. Each is described below; the older `python3 -m ecadlib.<module>` form still works.
 
 The UI and MCP server write everything to one workspace folder (default `./ecadlib_workspace`). It has these subfolders:
 * `uploads/`
@@ -480,16 +505,27 @@ python3 -m tests.test_offline
   * `unverified (source unreachable)`, which is kept separate on purpose so a network failure is never reported as "needs generation"
 * **Providers** (`providers.py`, interface `lookup(line) -> SourceResult`, raising `NotConfigured`):
 
-  | provider | auth needed | state in prototype |
-  |---|---|---|
-  | `jlcpcb_search` | none: anonymous JSON POST to `jlcpcb.com/api/overseas-pcb-order/v1/shoppingCart/smtGood/selectSmtComponentList` (taken from easyeda2kicad 1.0.1 `search_jlcpcb_components`; its docstring says "Works anonymously") | implemented; MPN → LCSC by exact normalised match |
-  | `easyeda` | none: `GET https://easyeda.com/api/products/{LCSC}/components` with `Referer: https://easyeda.com/` | implemented; parses `result.dataStr.head.c_para`, `packageDetail.dataStr.shape` and `SVGNODE~{…c_etype: outline3D}` for 3D, following easyeda2kicad's importer |
-  | `digikey` | OAuth2 client credentials (`DIGIKEY_CLIENT_ID/SECRET`), Product Information API v4 | stub |
-  | `mouser` | `MOUSER_API_KEY` (Search API) | stub |
-  | `nexar` | OAuth2 client credentials (`NEXAR_CLIENT_ID/SECRET`), GraphQL, quota-limited | stub |
-  | `snapmagic` | partner token only, with no self-serve public API | stub |
-  | `samacsys` | account plus Library Loader or partner access, with no documented public REST API | stub |
-
+  Default order: `nexar,digikey,mouser,jlcpcb_search,easyeda`. The official APIs come first; each is skipped with a
+  "not configured" note until its key is set. None of them hands out symbol or footprint geometry, so they identify
+  the part (maker, description, datasheet link, package, and the LCSC number when LCSC sells it) and the EasyEDA
+  route or the datasheet reader supplies the CAD data.
+
+  | provider | official? | auth needed | what it gives |
+  |---|---|---|---|
+  | `nexar` | yes (Octopart / Altium supply API) | OAuth2 client credentials (`NEXAR_CLIENT_ID/SECRET` or `NEXAR_SUPPLY_TOKEN`), GraphQL, quota-limited | MPN match, maker, description, best datasheet, LCSC number from LCSC's offer |
+  | `digikey` | yes (Product Information API v4) | OAuth2 client credentials (`DIGIKEY_CLIENT_ID/SECRET`) | MPN match, maker, description, datasheet, package |
+  | `mouser` | yes (Search API v1) | `MOUSER_API_KEY` | MPN match, maker, description, datasheet |
+  | `jlcpcb_search` | **no**: anonymous JSON POST to `jlcpcb.com/api/overseas-pcb-order/v1/shoppingCart/smtGood/selectSmtComponentList` (from easyeda2kicad 1.0.1) | none | MPN → LCSC, only when no official source found the LCSC number |
+  | `easyeda` | **no**: `GET https://easyeda.com/api/products/{LCSC}/components` with `Referer: https://easyeda.com/` | none | the symbol, footprint and 3D data (the only free source of ready CAD data) |
+  | `snapmagic` | partner token only, no self-serve public API | | stub |
+  | `samacsys` | account plus Library Loader or partner access, no documented public REST API | | stub |
+
+  * `[providers] unofficial = false` in `ecadlib.toml` keeps the two undocumented endpoints out entirely (triage, the
+    librarian's EasyEDA source, the UI). Parts then come from your libraries, the KiCad libraries, the standard
+    packages and the datasheet reader.
+  * `ecadlib sources-check` asks both unofficial endpoints about known parts (NE555DR, LM358DR, RP2040) and checks the
+    converter still gives the right pad and pin counts. `.github/workflows/sources-canary.yml` runs it every Monday and
+    keeps the raw answers as an artifact, so a change on their side shows up as a red run, not as broken user parts.
   * easyeda2kicad 1.0.1 calls `/components` with no `?version=`. The `?version=6.4.19.5` suffix comes from older releases; I kept it, and it is untested.
   * easyeda2kicad 1.0.1 also knows `pro.easyeda.com/api/components/searchByNumbers` (LCSC → v2 UUID, unauthenticated). Its other v2 endpoints are marked "requires auth" in its source.
   * I found no public, unauthenticated LCSC search endpoint. The `wmsc.lcsc.com` endpoints are undocumented and were also blocked here.
@@ -641,6 +677,10 @@ python3 -m ecadlib.altium365 plan examples/sample_bom.csv --triage out/triage_sa
                                                                      #    add --models out/altium_models_kicad (section 6) -> 14 ready
 ```
 
+**Altium can now build these files itself.** Every library written here also gets a plain-text recipe beside it
+(`<file>.ecadbuild`), and the install script lets Altium rebuild each library from it with its own scripting API
+before installing it. See [docs/altium-native.md](docs/altium-native.md) and `ecadlib altium-native`.
+
 No dependencies beyond the standard library. `cfb.py` writes the OLE2 container (v3, 512-byte sectors, mini stream, DIFAT for files over ~7 MB). `altium_lib.py` builds the Altium streams inside it. The record layouts are ported from **AltiumSharp** (C#, Apache-2.0; attribution in the file header and `NOTICE`). `altium-designer-mcp` (GPL-3.0) was read for notes only, and none of its code is used.
 
 What gets written:
@@ -844,7 +884,10 @@ Writes what the librarian built for Altium as a KiCad library: `mylib.kicad_sym`
 * **Checks:** every file parses with `ecadlib.sexpr`, each footprint passes release_check's footprint rule at the level the release check recorded, and symbol pins are checked against footprint pads. **In KiCad itself** (7.0.11, see section 28): the `fp-lib-table` resolves in a KiCad project and its footprints match the library; KiCad 7 refuses the KiCad 8 symbol library as such, and loads it with the two KiCad 8 tokens (`exclude_from_sim`, `generator_version`) removed, every pin, graphic and field unchanged. KiCad 8, 9 and 10 were not run here. A KiCad 7 symbol's `ki_description` becomes the `Description` field.
 * **License:** KiCad library content is CC-BY-SA 4.0. An export that includes some gets a `NOTICE.txt`, and the export stays out of git (`out/kicad/` is in `.gitignore`).
 
-## 11b. `eagle_export.py` and `easyeda_pro_export.py`: Fusion Electronics / EAGLE and EasyEDA Pro
+## 11b. `eagle_export.py` and `easyeda_pro_export.py`: Fusion Electronics / EAGLE and EasyEDA Pro (experimental)
+
+> **Experimental.** ecadlib focuses on Altium and KiCad. These two exports keep working and keep their read-back
+> checks, but they get no new features and may be removed in a later release.
 
 ```
 ecadlib eagle-export out/librarian/plan.json -o out/fusion --name mylib [--kicad out/kicad] [--include-held] [--offline]
@@ -1028,7 +1071,7 @@ python3 -m tests.test_sim_models
 * an Altium 365 part list (an `altium365` state file, or JSON in the `a365_sync` shape `{name, folder, parameters, symbol, footprint}`): folders and parameters;
 * KiCad `.kicad_sym`/`.pretty`, and BOM/parts spreadsheets (column names).
 
-Names are pattern-mined per category (`RES_{package}_{value}_{tolerance}`, `R{package}_{value}`, `{mpn}` ...) with value style (`4K7`, `4.7k`, `4.7kΩ`) detected. The written file says, for every setting, where it came from and how confident the guess is. `init` asks a question only where the evidence is split (the best pattern under 60% with a runner-up at 20% or more); `--yes` takes the best guess. If `ecadlib.toml` already exists, `init` shows a diff, writes the proposal to `ecadlib.toml.proposed` and changes nothing unless you confirm or pass `--force` (the old file is kept as `.bak`).
+Names are pattern-mined per category (`RES_{package}_{value}_{tolerance}`, `R{package}_{value}`, `{mpn}` ...) with value style (`4K7`, `4.7k`, `4.7kΩ`) detected. The written file says, for every setting, where it came from and how confident the guess is. Confidence counts how much of the library shows the convention, not only how much of the evidence agrees: a setting backed by fewer than 3 parts, footprints or symbols, or a footprint layer seen in fewer than half of the footprints (one `.Designator` in 48 footprints), is low. Low settings are not written; they are listed as comments at the top of the file, and ecadlib's default stays. The courtyard is never learned onto a layer that holds the library's 3D bodies, and a `.Designator` on a mechanical layer is not proposed when the library has silkscreen on the overlay. `init` asks a question only where the evidence is split (the best pattern under 60% with a runner-up at 20% or more); `--yes` takes the best guess. If `ecadlib.toml` already exists, `init` shows a diff, writes the proposal to `ecadlib.toml.proposed` and changes nothing unless you confirm or pass `--force` (the old file is kept as `.bak`).
 
 The UI has a **Library rules** card (type the folders to scan, review the proposals with their evidence, edit the TOML, save; replacing an existing file asks first and shows the diff). The MCP server has `propose_rules` and `save_rules`.
 

{ecadlib-0.3.0 → ecadlib-0.3.1}/README.md

@@ -1,10 +1,35 @@
-# ecad-librarian: "AI living library" prototypes
-
-These are small Python prototypes for an open-source tool that manages ECAD components for KiCad and Altium. The design has three parts:
-
-1. An LLM reads a datasheet mechanical drawing and fills `ecadlib/package_schema.json`.
-2. A deterministic generator turns that JSON into an IPC-7351B land pattern.
-3. A triage step works out which BOM lines already exist locally, which can be pulled from a public source, and which need a generated footprint.
+# ecadlib: a librarian for your parts
+
+ecadlib keeps your component library alive. Give it a BOM and it finds every symbol, footprint and 3D model you are
+missing, draws the ones nobody has from the datasheet, makes them match the rest of your library, holds anything in
+doubt for a person to sign off, and releases the rest to **Altium 365** or **KiCad**.
+
+* **BOM in.** Altium BOMs and ActiveBOMs, KiCad BOMs and schematics, or a hand-made CSV/XLSX. Each line comes back as
+  already in your library, available from a source, needs a footprint, or DNP.
+* **Official sources first.** Nexar, DigiKey and Mouser identify the part; symbols and footprints come from your own
+  libraries and the official KiCad libraries before anything else. EasyEDA/LCSC is an unofficial source, used after
+  those, and one setting (`[providers] unofficial = false`) turns it off.
+* **Drawn from the datasheet when nobody has it.** A datasheet reader fills a package description and a deterministic
+  IPC-7351B generator draws the land pattern. It works with Claude by default or the model you choose; you bring the
+  API key.
+* **Your house style.** `ecadlib style learn` reads your existing libraries and new parts follow the same naming,
+  descriptions, value formats and parameters.
+* **Review hold.** A release check runs on every part. Anything that fails it, or still needs a person, is held back
+  from Altium 365 until someone signs it off.
+* **Altium 365 release.** Parts go to your Altium 365 workspace, or out as `.SchLib`/`.PcbLib`, a database library
+  and KiCad libraries, from one plan.
+
+Install it with `pip install ecadlib` (v0.3.1, Python 3.10+), or on Windows run the installer from the
+[Releases page](https://github.com/oliBrowne/PCBLIVINGLIBRARY/releases). It is free and open source under the MIT
+licence. Website: [pcblivinglibrary.vercel.app](https://pcblivinglibrary.vercel.app).
+
+**Supported tools:** Altium (Altium 365 first) and KiCad are the supported targets: they get the testing, the
+benchmarks and the fixes. The Fusion Electronics / EAGLE and EasyEDA Pro exports (section 11b) still work but are
+**experimental**: kept as they are, not a focus, and they may be removed.
+
+**Where it's going:** [docs/PRODUCT_SPEC.md](docs/PRODUCT_SPEC.md) says who ecadlib is for, what it must do and how
+success is measured; [ROADMAP.md](ROADMAP.md) lists what has shipped and the next milestones (v0.3.1, v0.4.0, v0.5.0)
+with their dates.
 
 ## Start here (no terminal needed)
 
@@ -17,7 +42,7 @@ who use the command line or work on ecadlib itself (section 38 covers how the in
 ## Quick start
 
 ```
-pip install -e .                 # from this checkout (Python 3.10+); `pip install ecadlib` once a release is on PyPI
+pip install ecadlib              # Python 3.10+ (or `pip install -e .` from this checkout)
 ecadlib demo                     # about a second, offline, no API keys: a small library in ./ecadlib-demo
 ecadlib init                     # a few questions -> ecadlib.toml, then a setup check and the next commands
 ecadlib librarian my_bom.csv -o ecadlib_workspace/librarian/my_bom   # fill every missing part; `ecadlib status` shows it
@@ -46,7 +71,7 @@ See section 32 for the first-run commands in detail.
 Install it with pip (Python 3.10 or later):
 
 ```
-pip install ecadlib                 # once a release is on PyPI (see Releases below)
+pip install ecadlib                 # from PyPI
 pip install "ecadlib[pdf]"          # pypdf trims datasheets to --pages
 pip install -e ".[dev]"             # from a checkout: editable, plus everything the test suite uses
 ```
@@ -95,7 +120,7 @@ That gives you a single `ecadlib` command (`python -m ecadlib` works too). There
    ```
 
    Its tools are `workspace_info`, `triage_bom` (with `summary_only` for large BOMs), `preview_footprint`, `approve_footprint`, `librarian_run` (fill every missing part, then the release check), `release_check` (with `allow` for parts a person has signed off), `held_parts`, `part_candidates` and `choose_part` (fix a held part), `approval_status` and `approve_part` (sign-off; `user` is required, the agent must pass the person's own name), `find_duplicates` (with `merge`), `build_altium_models`, `export_altium_dblib`, `altium365_plan`, `altium365_push` (dry run unless `dry_run` is false; held parts are never pushed), `sim_models` (SPICE/IBIS models; `attach` writes them) and `list_example_specs`.
-3. **CLI**, for scripts and CI: `ecadlib triage`, `ecadlib footprint`, `ecadlib check`, `ecadlib footprint-bench`, `ecadlib dblib`, `ecadlib dblib-sync`, `ecadlib altium-lib`, `ecadlib altium365`, `ecadlib kicad-export` (the library as KiCad files, section 11), `ecadlib eagle-export` and `ecadlib easyeda-export` (Fusion Electronics / EAGLE and EasyEDA Pro, section 11b), `ecadlib resolve`, `ecadlib approve`, `ecadlib dedupe`, `ecadlib sourcing`, `ecadlib step-gen`, `ecadlib upkeep` (section 15), `ecadlib a365`, `ecadlib project`, `ecadlib where-used` and `ecadlib sim-models` (section 17), `ecadlib init` and `ecadlib rules` (section 18), `ecadlib demo` (section 32), `ecadlib kicad-pcm` and `ecadlib altium-pkg` (section 31), `ecadlib ai` (section 33), `ecadlib symbol` (section 19), `ecadlib datasheet`, `ecadlib team`, `ecadlib agent` (the library agent, section 20), `ecadlib agent-watch` (21), `ecadlib queue` (22), `ecadlib visual-check` (23), `ecadlib migrate` and `ecadlib rebuild` (35). Run `ecadlib <command> -h` for options. Each is described below; the older `python3 -m ecadlib.<module>` form still works.
+3. **CLI**, for scripts and CI: `ecadlib triage`, `ecadlib footprint`, `ecadlib check`, `ecadlib footprint-bench`, `ecadlib dblib`, `ecadlib dblib-sync`, `ecadlib altium-lib`, `ecadlib altium365`, `ecadlib kicad-export` (the library as KiCad files, section 11), `ecadlib eagle-export` and `ecadlib easyeda-export` (Fusion Electronics / EAGLE and EasyEDA Pro, experimental, section 11b), `ecadlib resolve`, `ecadlib approve`, `ecadlib dedupe`, `ecadlib sourcing`, `ecadlib step-gen`, `ecadlib upkeep` (section 15), `ecadlib a365`, `ecadlib project`, `ecadlib where-used` and `ecadlib sim-models` (section 17), `ecadlib init` and `ecadlib rules` (section 18), `ecadlib demo` (section 32), `ecadlib kicad-pcm` and `ecadlib altium-pkg` (section 31), `ecadlib ai` (section 33), `ecadlib symbol` (section 19), `ecadlib datasheet`, `ecadlib team`, `ecadlib agent` (the library agent, section 20), `ecadlib agent-watch` (21), `ecadlib queue` (22), `ecadlib visual-check` (23), `ecadlib migrate` and `ecadlib rebuild` (35). Run `ecadlib <command> -h` for options. Each is described below; the older `python3 -m ecadlib.<module>` form still works.
 
 The UI and MCP server write everything to one workspace folder (default `./ecadlib_workspace`). It has these subfolders:
 * `uploads/`
@@ -426,16 +451,27 @@ python3 -m tests.test_offline
   * `unverified (source unreachable)`, which is kept separate on purpose so a network failure is never reported as "needs generation"
 * **Providers** (`providers.py`, interface `lookup(line) -> SourceResult`, raising `NotConfigured`):
 
-  | provider | auth needed | state in prototype |
-  |---|---|---|
-  | `jlcpcb_search` | none: anonymous JSON POST to `jlcpcb.com/api/overseas-pcb-order/v1/shoppingCart/smtGood/selectSmtComponentList` (taken from easyeda2kicad 1.0.1 `search_jlcpcb_components`; its docstring says "Works anonymously") | implemented; MPN → LCSC by exact normalised match |
-  | `easyeda` | none: `GET https://easyeda.com/api/products/{LCSC}/components` with `Referer: https://easyeda.com/` | implemented; parses `result.dataStr.head.c_para`, `packageDetail.dataStr.shape` and `SVGNODE~{…c_etype: outline3D}` for 3D, following easyeda2kicad's importer |
-  | `digikey` | OAuth2 client credentials (`DIGIKEY_CLIENT_ID/SECRET`), Product Information API v4 | stub |
-  | `mouser` | `MOUSER_API_KEY` (Search API) | stub |
-  | `nexar` | OAuth2 client credentials (`NEXAR_CLIENT_ID/SECRET`), GraphQL, quota-limited | stub |
-  | `snapmagic` | partner token only, with no self-serve public API | stub |
-  | `samacsys` | account plus Library Loader or partner access, with no documented public REST API | stub |
-
+  Default order: `nexar,digikey,mouser,jlcpcb_search,easyeda`. The official APIs come first; each is skipped with a
+  "not configured" note until its key is set. None of them hands out symbol or footprint geometry, so they identify
+  the part (maker, description, datasheet link, package, and the LCSC number when LCSC sells it) and the EasyEDA
+  route or the datasheet reader supplies the CAD data.
+
+  | provider | official? | auth needed | what it gives |
+  |---|---|---|---|
+  | `nexar` | yes (Octopart / Altium supply API) | OAuth2 client credentials (`NEXAR_CLIENT_ID/SECRET` or `NEXAR_SUPPLY_TOKEN`), GraphQL, quota-limited | MPN match, maker, description, best datasheet, LCSC number from LCSC's offer |
+  | `digikey` | yes (Product Information API v4) | OAuth2 client credentials (`DIGIKEY_CLIENT_ID/SECRET`) | MPN match, maker, description, datasheet, package |
+  | `mouser` | yes (Search API v1) | `MOUSER_API_KEY` | MPN match, maker, description, datasheet |
+  | `jlcpcb_search` | **no**: anonymous JSON POST to `jlcpcb.com/api/overseas-pcb-order/v1/shoppingCart/smtGood/selectSmtComponentList` (from easyeda2kicad 1.0.1) | none | MPN → LCSC, only when no official source found the LCSC number |
+  | `easyeda` | **no**: `GET https://easyeda.com/api/products/{LCSC}/components` with `Referer: https://easyeda.com/` | none | the symbol, footprint and 3D data (the only free source of ready CAD data) |
+  | `snapmagic` | partner token only, no self-serve public API | | stub |
+  | `samacsys` | account plus Library Loader or partner access, no documented public REST API | | stub |
+
+  * `[providers] unofficial = false` in `ecadlib.toml` keeps the two undocumented endpoints out entirely (triage, the
+    librarian's EasyEDA source, the UI). Parts then come from your libraries, the KiCad libraries, the standard
+    packages and the datasheet reader.
+  * `ecadlib sources-check` asks both unofficial endpoints about known parts (NE555DR, LM358DR, RP2040) and checks the
+    converter still gives the right pad and pin counts. `.github/workflows/sources-canary.yml` runs it every Monday and
+    keeps the raw answers as an artifact, so a change on their side shows up as a red run, not as broken user parts.
   * easyeda2kicad 1.0.1 calls `/components` with no `?version=`. The `?version=6.4.19.5` suffix comes from older releases; I kept it, and it is untested.
   * easyeda2kicad 1.0.1 also knows `pro.easyeda.com/api/components/searchByNumbers` (LCSC → v2 UUID, unauthenticated). Its other v2 endpoints are marked "requires auth" in its source.
   * I found no public, unauthenticated LCSC search endpoint. The `wmsc.lcsc.com` endpoints are undocumented and were also blocked here.
@@ -587,6 +623,10 @@ python3 -m ecadlib.altium365 plan examples/sample_bom.csv --triage out/triage_sa
                                                                      #    add --models out/altium_models_kicad (section 6) -> 14 ready
 ```
 
+**Altium can now build these files itself.** Every library written here also gets a plain-text recipe beside it
+(`<file>.ecadbuild`), and the install script lets Altium rebuild each library from it with its own scripting API
+before installing it. See [docs/altium-native.md](docs/altium-native.md) and `ecadlib altium-native`.
+
 No dependencies beyond the standard library. `cfb.py` writes the OLE2 container (v3, 512-byte sectors, mini stream, DIFAT for files over ~7 MB). `altium_lib.py` builds the Altium streams inside it. The record layouts are ported from **AltiumSharp** (C#, Apache-2.0; attribution in the file header and `NOTICE`). `altium-designer-mcp` (GPL-3.0) was read for notes only, and none of its code is used.
 
 What gets written:
@@ -790,7 +830,10 @@ Writes what the librarian built for Altium as a KiCad library: `mylib.kicad_sym`
 * **Checks:** every file parses with `ecadlib.sexpr`, each footprint passes release_check's footprint rule at the level the release check recorded, and symbol pins are checked against footprint pads. **In KiCad itself** (7.0.11, see section 28): the `fp-lib-table` resolves in a KiCad project and its footprints match the library; KiCad 7 refuses the KiCad 8 symbol library as such, and loads it with the two KiCad 8 tokens (`exclude_from_sim`, `generator_version`) removed, every pin, graphic and field unchanged. KiCad 8, 9 and 10 were not run here. A KiCad 7 symbol's `ki_description` becomes the `Description` field.
 * **License:** KiCad library content is CC-BY-SA 4.0. An export that includes some gets a `NOTICE.txt`, and the export stays out of git (`out/kicad/` is in `.gitignore`).
 
-## 11b. `eagle_export.py` and `easyeda_pro_export.py`: Fusion Electronics / EAGLE and EasyEDA Pro
+## 11b. `eagle_export.py` and `easyeda_pro_export.py`: Fusion Electronics / EAGLE and EasyEDA Pro (experimental)
+
+> **Experimental.** ecadlib focuses on Altium and KiCad. These two exports keep working and keep their read-back
+> checks, but they get no new features and may be removed in a later release.
 
 ```
 ecadlib eagle-export out/librarian/plan.json -o out/fusion --name mylib [--kicad out/kicad] [--include-held] [--offline]
@@ -974,7 +1017,7 @@ python3 -m tests.test_sim_models
 * an Altium 365 part list (an `altium365` state file, or JSON in the `a365_sync` shape `{name, folder, parameters, symbol, footprint}`): folders and parameters;
 * KiCad `.kicad_sym`/`.pretty`, and BOM/parts spreadsheets (column names).
 
-Names are pattern-mined per category (`RES_{package}_{value}_{tolerance}`, `R{package}_{value}`, `{mpn}` ...) with value style (`4K7`, `4.7k`, `4.7kΩ`) detected. The written file says, for every setting, where it came from and how confident the guess is. `init` asks a question only where the evidence is split (the best pattern under 60% with a runner-up at 20% or more); `--yes` takes the best guess. If `ecadlib.toml` already exists, `init` shows a diff, writes the proposal to `ecadlib.toml.proposed` and changes nothing unless you confirm or pass `--force` (the old file is kept as `.bak`).
+Names are pattern-mined per category (`RES_{package}_{value}_{tolerance}`, `R{package}_{value}`, `{mpn}` ...) with value style (`4K7`, `4.7k`, `4.7kΩ`) detected. The written file says, for every setting, where it came from and how confident the guess is. Confidence counts how much of the library shows the convention, not only how much of the evidence agrees: a setting backed by fewer than 3 parts, footprints or symbols, or a footprint layer seen in fewer than half of the footprints (one `.Designator` in 48 footprints), is low. Low settings are not written; they are listed as comments at the top of the file, and ecadlib's default stays. The courtyard is never learned onto a layer that holds the library's 3D bodies, and a `.Designator` on a mechanical layer is not proposed when the library has silkscreen on the overlay. `init` asks a question only where the evidence is split (the best pattern under 60% with a runner-up at 20% or more); `--yes` takes the best guess. If `ecadlib.toml` already exists, `init` shows a diff, writes the proposal to `ecadlib.toml.proposed` and changes nothing unless you confirm or pass `--force` (the old file is kept as `.bak`).
 
 The UI has a **Library rules** card (type the folders to scan, review the proposals with their evidence, edit the TOML, save; replacing an existing file asks first and shows the diff). The MCP server has `propose_rules` and `save_rules`.
 

{ecadlib-0.3.0 → ecadlib-0.3.1}/ecadlib/__init__.py

@@ -1,3 +1,3 @@
 """ecadlib - prototype tooling for an AI-assisted "living" ECAD component library."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{ecadlib-0.3.0 → ecadlib-0.3.1}/ecadlib/altium365.py

@@ -247,6 +247,8 @@ def push(items, client, ws, dry_run=False, note="ecadlib sync", policy=None, rul
     from .approvals import push_block
     from .rules import house_item
     from .a365_sync import is_a365
+    # sign-off is checked on the item as it was approved (ecadlib's parameter names: the content hash covers them)
+    blocks = [push_block(i, policy) for i in items]
     # a pulled item already carries the workspace's own parameter names: renaming it would rename them there
     items = [i if is_a365(i) else house_item(i, rules) for i in items]
     defs = {} if dry_run else client.release_defs(ws)
@@ -255,14 +257,13 @@ def push(items, client, ws, dry_run=False, note="ecadlib sync", policy=None, rul
         if p not in uploaded:
             uploaded[p] = "<fileId>" if dry_run else client.upload(p)
         return uploaded[p]
-    for it in items:
+    for it, block in zip(items, blocks):
         res = {"name": it["name"], "action": "", "detail": ""}
         if it.get("status") == "held":         # release_check held it back: no release, no parameter update
             res["action"], res["detail"] = "skip", "held: " + "; ".join(it.get("hold_reasons") or ["release check"])
             results.append(res)
             continue
-        block = push_block(it, policy)         # sign-off policy not met, or a dedupe duplicate
-        if block:
+        if block:                              # sign-off policy not met, or a dedupe duplicate
             res["action"], res["detail"] = "skip", block
             results.append(res)
             continue
@@ -325,7 +326,7 @@ def main(argv=None):
     from . import rules as RU
 
     if a.cmd == "plan":
-        if Path(a.out).is_dir() or a.out.endswith(("/", "\\")):      # -o out/a365: the plan file inside that folder
+        if Path(a.out).is_dir() or a.out.endswith(("/", "\\")) or not Path(a.out).suffix:   # -o out/a365: the plan file inside that folder
             a.out = str(Path(a.out) / "plan.json")
         rules = RU.load(a.rules, start=Path(a.out).parent)
         lines, _ = read_bom(a.bom, RU.bom_columns(rules))