uniwire 0.1.0__tar.gz

uniwire-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+uv.lock
+
+# Tools
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+*.log
+
+# Generated output
+out/
+site/
+viewer/dist/
+viewer/examples/
+viewer/version.json
+viewer/favicon.svg
+viewer/favicon-16.svg
+
+# Secrets
+.env
+.env.*
+
+# Editors and systems
+.DS_Store
+.idea/
+.vscode/

uniwire-0.1.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to the uniwire format and to the `uniwire` Python library are documented here.
+The format and the library are versioned separately: the format follows `1.y.z` (see
+[SPEC §9](https://uniwire.sh/docs/SPEC/#9-extensibility-and-versions)), the library follows its own semantic
+version.
+
+## Unreleased
+
+## 0.1.0 (format 1.0)
+
+First release of the uniwire format and of the `uniwire` Python library (Apache-2.0; specification text under
+CC BY 4.0).
+
+* Format 1.0: `*.uniwire.json` documents describing an installation as a power tree (sources, devices, loads)
+  plus `links` for everything outside the tree; typed nodes (53 types), templates, views; published JSON
+  Schema at <https://uniwire.sh/schema/v1/uniwire.schema.json>
+  ([specification](https://uniwire.sh/docs/SPEC/)).
+* Node types for utility supplies, MV/LV transformers, generators, UPS, PV, batteries, inverters, protective
+  and switching devices, instrument transformers, protection relays, insulation monitors, busbars, boards,
+  terminal blocks, loads, modular PLCs (ordered modules, roles, protocols, channel ports) and power supplies.
+* Common node fields (`count`, `circuit`, `un_V`, `ib_A`, `normal_state`, `locks`...), auxiliary devices outside
+  the tree (`devices[]`), addressable enclosures (`enclosures[]`), key interlocks (`interlocks[]`, `locks[]` on
+  nodes and links).
+* Link kinds `transfer`, `tie`, `bypass`, `parallel`, `infeed`, `earth`, `control`, `interlock`, `trip`,
+  `measure`, `data` and `key`, with optional cable, device and terminal / channel ports.
+* Structured `product` references on every node and PLC module; bill of materials as CSV (`uniwire bom`).
+* Validation with explicit messages (unknown fields, wrong units, broken references); any `1.y.z` document is
+  accepted.
+* Rule profiles: `core`, `nfc15100` (French dwellings), `iec60364` (cable current-carrying capacity from the
+  GUIA-BT-19 tables), PLC consistency checks, interlock check.
+* Single-line diagrams: automatic layout, automatic sheet splitting with cross-references, circuit schedule,
+  enclosure frames, title block, revisions and notes, top-down or bottom-up drawings.
+* Multi-line power diagrams derived from the same document: one line per conductor (L1, L2, L3, N, PE / PEN),
+  one contact per pole, RCD toroids, PEN split, transformer windings, motors, busbars as one rail per
+  conductor; `uniwire render --kind multi-line` for any document.
+* Colour modes per view: conductors (IEC 60445 or North-American colours), phase, source, status or voltage
+  level, with palette overrides and a legend.
+* Wire marking (the part of [UEP-0001](https://uniwire.sh/docs/uep/0001-terminals-and-wires/) that format 1.0
+  can carry): marking rules per view, manual marks in `cable.marks`, cable tags on the drawings; CSV exports
+  `uniwire wires`, `uniwire markers`, `uniwire cables`, and `uniwire marks [--write]`.
+* SVG output with a documented structure contract
+  ([Python API](https://uniwire.sh/docs/api/#svg-structure)); multi-sheet PDF with bookmarks and clickable
+  cross-sheet references.
+* English and French rendering (`meta.lang`); CLI messages follow `UNIWIRE_LANG`.
+* Code-first API `uniwire.build`: installations as Python code
+  ([guide](https://uniwire.sh/docs/build/)).
+* Command line `uniwire`: `validate`, `check`, `render`, `bom`, `wires`, `markers`, `cables`, `marks`,
+  `graph`, `normalize`, `schema`, `symbols`, `card`, `describe`, `patch`, `link`, `--version`.
+* Terminal / connectivity-node graph derived from the document, with CIM, IFC and IEC 61850 SCL mappings.
+* Tolerant reading of unambiguous near-miss values (`poles: 2`, `cores: "3G2.5"`, `range_A: [15, 45]`...), each
+  reported by the rule `core.normalized`; `installation.premises` scopes dwelling-only rules.
+* LLM tools ([guide](https://uniwire.sh/docs/llm/)): reference card generated from the model (`uniwire card`),
+  text outline with stable ids (`uniwire describe`), id-based edits (`uniwire patch`), flat node table, links that
+  open a document in the web editor (`uniwire link`, `viewer_url` in the MCP tool results).
+* MCP server `uniwire-mcp` (extra `uniwire[mcp]`): stdio and HTTP transports, tools to validate, check,
+  describe, patch, render and export documents, bundled examples; a public mode with bounded inputs,
+  worker processes and timeouts, short editor links (`--store`) and a usage log without caller addresses,
+  used by the hosted endpoint <https://mcp.uniwire.sh/mcp>; every tool has a title and read-only annotations;
+  check results state their scope (automatic checks, not a conformity certificate).
+  Setup for ChatGPT, Claude, Cursor and VS Code: [uniwire in your assistant](https://uniwire.sh/docs/assistants/).
+* LLM evaluation tasks with a runner that makes no network calls
+  ([evals/llm](https://github.com/uniwire-dev/uniwire/tree/main/evals/llm)).
+* Hardened parsing: bounded quantity and reference parsers, nesting limit, CSV formula neutralisation,
+  XML-safe SVG, PDF and CSV output.
+* 52 example documents ([examples](https://github.com/uniwire-dev/uniwire/tree/main/examples)): dwellings,
+  commercial and industrial boards, MV/LV substations, standby sources, PV, EV charging, UPS, PLCs.
+* Optional IEC 81346-2 class table in the separate data package `uniwire-data-iec81346` (CC BY-SA 4.0),
+  `pip install "uniwire[iec81346]"`.
+* Draft proposal [UEP-0001 "Terminals, terminal strips and wires"](https://uniwire.sh/docs/uep/0001-terminals-and-wires/)
+  for format 2.0.

uniwire-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

uniwire-0.1.0/NOTICE

@@ -0,0 +1,31 @@
+uniwire: open standard and reference library for describing electrical installations
+(single-line and multi-line diagrams)
+Copyright 2026 The uniwire contributors
+https://github.com/uniwire-dev/uniwire
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+The uniwire specification text (docs/SPEC.md) is licensed under the Creative Commons Attribution 4.0
+International licence (CC BY 4.0), see docs/LICENSE-SPEC.md.
+
+uniwire symbols are original drawings made for this project.
+
+Third-party data:
+- Current-carrying capacity tables (src/uniwire/registry/data/iz_tables.json) reproduce values
+  from the public Spanish technical guide GUIA-BT-19 (tables taken from UNE 20460-5-523:2004),
+  cited in the file header (see src/uniwire/registry/data/LICENSES.md).
+
+Optional data package (distributed separately, not covered by the Apache License):
+- uniwire-data-iec81346 (packages/uniwire-data-iec81346), installed with
+  `pip install "uniwire[iec81346]"`, contains an IEC 81346-2:2019 class table derived from the
+  Wikipedia article "IEC 81346" and is licensed under CC BY-SA 4.0 (see its README and LICENSE).
+
+Fonts:
+- No font files are included. The documentation theme and the web viewer (viewer/) refer to the Public
+  Sans and JetBrains Mono fonts (SIL Open Font License 1.1) served by the uniwire.sh website at
+  /assets/fonts/, and fall back to system fonts when built and served on their own.
+
+Used but not bundled:
+- The web viewer loads Pyodide (Mozilla Public License 2.0) and CodeMirror 6 (MIT) from public CDNs at run
+  time.
+- The documentation is built with MkDocs and Material for MkDocs (BSD-2-Clause and MIT).

uniwire-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: uniwire
+Version: 0.1.0
+Summary: Electrical diagrams, as code: an open standard to describe electrical installations, with validation, rules, BOM, wire lists and single-line / multi-line SVG/PDF drawings
+Project-URL: Homepage, https://uniwire.sh
+Project-URL: Documentation, https://uniwire.sh/docs/
+Project-URL: Repository, https://github.com/uniwire-dev/uniwire
+Project-URL: Issues, https://github.com/uniwire-dev/uniwire/issues
+Project-URL: Changelog, https://github.com/uniwire-dev/uniwire/blob/main/CHANGELOG.md
+Author: uniwire contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: CAD,IEC 60364,IEC 60617,NF C 15-100,diagram as code,electrical,mcp,multi-line diagram,one-line diagram,schema unifilaire,single-line diagram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.20; extra == 'dev'
+Requires-Dist: mcp>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: reportlab>=4; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: iec81346
+Requires-Dist: uniwire-data-iec81346; extra == 'iec81346'
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0; extra == 'mcp'
+Provides-Extra: pdf
+Requires-Dist: reportlab>=4; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# uniwire
+
+**Electrical diagrams, as code.**
+
+An open standard to describe electrical installations, and the reference Python library that validates
+them, checks them against rules and draws their single-line and multi-line diagrams.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/uniwire-dev/uniwire/ci.yml?branch=main&label=CI)](https://github.com/uniwire-dev/uniwire/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/uniwire)](https://pypi.org/project/uniwire/)
+[![Python](https://img.shields.io/pypi/pyversions/uniwire)](https://pypi.org/project/uniwire/)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/uniwire-dev/uniwire/blob/main/LICENSE)
+
+You describe the **installation** (sources, protective devices, cables, loads, PLCs) in a `*.uniwire.json`
+file or in Python, and uniwire computes the drawings. No coordinates, no CAD file: a text file you can
+review and diff.
+
+* **Format**: `*.uniwire.json`, format 1.0, defined by the [specification](https://uniwire.sh/docs/SPEC/)
+  and validated by a published JSON Schema: <https://uniwire.sh/schema/v1/uniwire.schema.json>.
+* **Library**: `pip install uniwire`: Python API, code-first builder and the `uniwire` command line.
+* **Documentation**: <https://uniwire.sh/docs/>
+* **Web viewer**: <https://uniwire.sh/viewer/>, paste a document to validate, check and draw it in the browser.
+
+## Features
+
+* **Single-line and multi-line diagrams** from the same document: the multi-line view derives every
+  conductor (L1, L2, L3, N, PE, PEN) from the single-line data, with no extra input.
+* **53 node types**: utility grid, transformers, generators, UPS, PV, batteries, inverters; breakers,
+  RCDs, RCBOs, fuses, switch-disconnectors, contactors, motor starters, transfer switches, SPDs,
+  protection relays, instrument transformers, insulation monitors; busbars, boards, terminal blocks;
+  lighting, sockets, heating, motors, EV chargers, modular PLCs and more.
+* **Tree + links**: the power tree is the backbone; transfers, bus ties, infeeds, earthing, control,
+  interlocks, trips, measurements and data buses are links. A terminal / connectivity-node graph is
+  derived automatically, with CIM, IFC and IEC 61850 SCL mappings.
+* **Closed typing and unit-suffixed fields**: `in_A`, `idn_mA`, `section_mm2`, `p_kW`; unknown fields are
+  errors (`calibre` instead of `in_A` is caught), extensions live in `ext`. Templates declare a device once.
+* **Rule profiles**: `core` (always), `nfc15100` (French dwellings), `iec60364` (cable current-carrying
+  capacity), plus PLC consistency checks.
+* **Bill of materials**: structured `product` references (manufacturer, part number, range, accessories)
+  on any node or PLC module, aggregated to CSV (`uniwire bom`).
+* **Wire and cable marking**: marking rules per view (manual, sequential, per potential, pattern), marks
+  drawn on the multi-line diagram, and CSV exports: wire list (`uniwire wires`), wire marker list
+  (`uniwire markers`), cable schedule (`uniwire cables`); `uniwire marks --write` freezes the marks.
+* **Colour modes**: conductors in their IEC 60445 or North-American colours, or colouring by phase,
+  source, status or voltage level.
+* **Sheets**: paper size, sub-tree views, automatic sheet splitting with cross-references, circuit schedule,
+  enclosure frames, title block, revisions and notes. **SVG** output is deterministic and diff-friendly;
+  the multi-sheet **PDF** has clickable links between sheets.
+* **English and French rendering**, selected per document with `meta.lang`.
+* **LLM tooling**: a reference card generated from the model (`uniwire card`), a text outline with
+  stable ids (`uniwire describe`), id-based edits (`uniwire patch`), an MCP server (`uniwire-mcp`, stdio)
+  and a hosted MCP endpoint at <https://mcp.uniwire.sh/mcp>, plus
+  [llms.txt](https://uniwire.sh/llms.txt) for assistants (full reference card
+  included). Setup for ChatGPT, Claude, Cursor and VS Code:
+  [uniwire in your assistant](https://uniwire.sh/docs/assistants/); details in
+  [LLM tools](https://uniwire.sh/docs/llm/).
+
+## Gallery
+
+<table>
+<tr>
+<td width="50%"><a href="https://github.com/uniwire-dev/uniwire/blob/main/examples/02_house_3_bedrooms_tt.uniwire.json"><img src="https://github.com/uniwire-dev/uniwire/raw/main/docs/gallery/02_house_3_bedrooms_tt.png" alt="French house, TT, single-line diagram"></a><br><sub>French house, TT (NF C 15-100), single-line</sub></td>
+<td width="50%"><a href="https://github.com/uniwire-dev/uniwire/blob/main/examples/06_german_single_family_house.uniwire.json"><img src="https://github.com/uniwire-dev/uniwire/raw/main/docs/gallery/06_german_single_family_house.png" alt="German house, TN-C-S, multi-line diagram in conductor colours"></a><br><sub>German house, TN-C-S, multi-line in conductor colours</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="https://github.com/uniwire-dev/uniwire/blob/main/examples/18_office_building_main_lv_switchboard.uniwire.json"><img src="https://github.com/uniwire-dev/uniwire/raw/main/docs/gallery/18_office_building_main_lv_switchboard.png" alt="Office building main LV switchboard"></a><br><sub>Office building, main LV switchboard</sub></td>
+<td width="50%"><a href="https://github.com/uniwire-dev/uniwire/blob/main/examples/25_poste_hta_bt_1000kva.uniwire.json"><img src="https://github.com/uniwire-dev/uniwire/raw/main/docs/gallery/25_poste_hta_bt_1000kva.png" alt="MV/LV substation, 1000 kVA"></a><br><sub>MV/LV substation, 1000 kVA</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="https://github.com/uniwire-dev/uniwire/blob/main/examples/27_standby_generator_ats_load_shedding.uniwire.json"><img src="https://github.com/uniwire-dev/uniwire/raw/main/docs/gallery/27_standby_generator_ats_load_shedding.png" alt="Standby generator, automatic transfer switch, load shedding"></a><br><sub>Standby generator, ATS, load shedding</sub></td>
+<td width="50%"><a href="https://github.com/uniwire-dev/uniwire/blob/main/examples/24_factory_mcc_motor_starters.uniwire.json"><img src="https://github.com/uniwire-dev/uniwire/raw/main/docs/gallery/24_factory_mcc_motor_starters.png" alt="Motor control centre, multi-line diagram with wire marks"></a><br><sub>Motor control centre, multi-line with wire marks</sub></td>
+</tr>
+</table>
+
+All 52 examples are in [examples/](https://github.com/uniwire-dev/uniwire/tree/main/examples) and listed in the
+[documentation](https://uniwire.sh/docs/examples/); open any of them in the [web viewer](https://uniwire.sh/viewer/).
+
+## Install
+
+```bash
+pip install uniwire                 # validation, rules, SVG rendering, bill of materials, exports
+pip install "uniwire[pdf]"          # + PDF output (reportlab)
+pip install "uniwire[mcp]"          # + MCP server (uniwire-mcp)
+pip install "uniwire[iec81346]"     # + optional IEC 81346-2 class table (separate CC BY-SA 4.0 data package)
+```
+
+Python 3.10 or later. The only required dependency is pydantic.
+
+## Quickstart
+
+A document in JSON:
+
+```json
+{
+  "$schema": "https://uniwire.sh/schema/v1/uniwire.schema.json",
+  "uniwire": "1.0.0",
+  "profiles": ["nfc15100"],
+  "meta": { "title": "Small house", "lang": "en" },
+  "installation": { "earthing": "TT", "system": "1P+N", "un_V": 230 },
+  "templates": { "C16": { "type": "breaker", "in_A": 16, "curve": "C" } },
+  "sources": [
+    { "type": "grid", "label": "Utility", "children": [
+      { "type": "main_breaker", "ref": "-Q0", "range_A": "15-45", "in_A": 45, "idn_mA": 500, "selective": true,
+        "children": [
+          { "type": "rcd", "ref": "-Q1", "in_A": 40, "idn_mA": 30, "rcd_type": "A", "children": [
+            { "type": "breaker", "ref": "-Q11", "use": "C16", "cable": { "cores": "3G", "section_mm2": 1.5 },
+              "children": [ { "type": "lighting", "label": "Lighting", "points": 6 } ] },
+            { "type": "breaker", "ref": "-Q12", "in_A": 20, "curve": "C", "cable": { "cores": "3G", "section_mm2": 2.5 },
+              "children": [ { "type": "socket", "label": "Sockets", "points": 8 } ] }
+          ] }
+      ] }
+    ] }
+  ]
+}
+```
+
+The tree is the power flow (source, protective devices, loads); whatever falls outside the tree
+(transfer switches, bus ties, control and data connections) goes in `links`.
+
+```bash
+uniwire validate house.uniwire.json                 # schema + integrity
+uniwire check house.uniwire.json                    # rule profiles (exit code 1 on errors)
+uniwire render house.uniwire.json                   # SVG sheets in out/house/
+uniwire render house.uniwire.json -f pdf -o house.pdf
+uniwire render house.uniwire.json --kind multi-line # multi-line power diagram
+uniwire bom house.uniwire.json -o house.bom.csv     # bill of materials
+uniwire wires house.uniwire.json                    # wire list (also: markers, cables, marks)
+uniwire card                                        # reference card for assistants
+```
+
+The same installation in Python:
+
+```python
+from uniwire.build import *
+
+with Installation("Small house", earthing="TT", system="1P+N", un="230 V", profiles=["nfc15100"]) as inst:
+    with Grid("Utility"), MainBreaker("-Q0", "15-45 A", idn="500 mA", selective=True):
+        with RCD("-Q1", "40 A", "30 mA", type="A"):
+            Breaker("-Q11", "C16", cable="3G1,5") >> Lighting("Lighting", points=6)
+            Breaker("-Q12", "C20", cable="3G2,5 18 m") >> Socket("Sockets", points=8)
+
+for finding in inst.check():
+    print(finding)
+inst.save("house.uniwire.json")
+inst.render("house.pdf")
+```
+
+`with` makes an element the parent of everything created inside it, `>>` chains elements, ratings and
+cables are written the way they appear on drawings (`"C16"`, `"3G2,5 18 m"`). See the
+[code-first API](https://uniwire.sh/docs/build/) and the [Python API and CLI](https://uniwire.sh/docs/api/).
+
+## Roadmap
+
+* **Terminals, terminal strips and wires**: [UEP-0001](https://uniwire.sh/docs/uep/0001-terminals-and-wires/),
+  a draft for format 2.0 (named ports, terminal strips, wires and cables as objects, potentials).
+* **Control schematics**: coils, auxiliary contacts with cross-references, terminal plans and wire numbers,
+  built on named ports.
+* **Exports**: DXF drawings, pandapower networks for load-flow and short-circuit studies.
+
+Ideas and format proposals are welcome: see
+[CONTRIBUTING.md](https://github.com/uniwire-dev/uniwire/blob/main/CONTRIBUTING.md).
+
+## Contributing
+
+Bug reports, examples, rules, symbols and translations are welcome. Read
+[CONTRIBUTING.md](https://github.com/uniwire-dev/uniwire/blob/main/CONTRIBUTING.md) (development setup, tests,
+uniwire Enhancement Proposals) and the
+[Code of Conduct](https://github.com/uniwire-dev/uniwire/blob/main/CODE_OF_CONDUCT.md). Report security issues
+privately, see [SECURITY.md](https://github.com/uniwire-dev/uniwire/blob/main/SECURITY.md).
+
+## Licences
+
+* Code, CLI and JSON Schema: [Apache License 2.0](https://github.com/uniwire-dev/uniwire/blob/main/LICENSE).
+* Specification text: [CC BY 4.0](https://github.com/uniwire-dev/uniwire/blob/main/docs/LICENSE-SPEC.md):
+  implement it freely, in any software.
+* Optional data package `uniwire-data-iec81346` (IEC 81346-2 class table): CC BY-SA 4.0, distributed
+  separately (`pip install "uniwire[iec81346]"`).
+
+See [NOTICE](https://github.com/uniwire-dev/uniwire/blob/main/NOTICE) for third-party notices.