Metadata-Version: 2.4
Name: buildwithtrace-converter
Version: 0.1.0
Summary: Trace EDA converter: .trace_sch/.trace_pcb <-> KiCad s-expression, plus the trace_parser. Single source of truth for the CLI, backend, and desktop.
Author-email: Trace <hello@buildwithtrace.com>
License: PROPRIETARY LICENSE
        
        Copyright (C) 2025-2026 Trace Developers Team. All Rights Reserved.
        
        This software and associated documentation files (the "Software") contained
        in this directory and its subdirectories are proprietary and confidential.
        
        RESTRICTIONS:
        - You may NOT copy, modify, merge, publish, distribute, sublicense, or sell
          copies of the Software.
        - You may NOT use the Software for any commercial or non-commercial purpose
          without explicit written permission from the copyright holders.
        - You may NOT reverse engineer, decompile, or disassemble the Software.
        - You may NOT create derivative works based on the Software.
        
        This Software is provided for reference only as part of the Trace open-source
        repository. The inclusion of this code in the repository does not grant any
        license or rights to use, copy, or distribute it.
        
        For licensing inquiries, contact: hello@buildwithtrace.com
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
        DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THIS SOFTWARE.
License-File: LICENSE
Keywords: converter,eda,kicad,pcb,schematic,trace
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: vectorsearch
Requires-Dist: numpy>=1.24; extra == 'vectorsearch'
Requires-Dist: onnxruntime>=1.16; extra == 'vectorsearch'
Requires-Dist: tokenizers>=0.15; extra == 'vectorsearch'
Description-Content-Type: text/markdown

# buildwithtrace-converter

The Trace EDA converter, extracted into a single installable package so the CLI,
backend, and desktop app stop carrying their own copies.

It converts between Trace's intermediate `.trace_sch` / `.trace_pcb` format and
KiCad's native `.kicad_sch` / `.kicad_pcb` s-expression format (both directions),
and exposes the `trace_parser` used to read the intermediate format.

- **Package (PyPI/dist) name:** `buildwithtrace-converter`
- **Import root:** `buildwithtrace_converter` (a self-contained top-level — deliberately NOT a `buildwithtrace.*` namespace, to avoid colliding with the CLI's `buildwithtrace` package and the backend's vendored `buildwithtrace.altium`)
- **GitHub:** `buildwithtrace/converter` (org, canonical) / `elcruzo/trace-converter` (personal)

## Install

```bash
# core (pure stdlib, no deps)
pip install buildwithtrace-converter

# with the optional vector-search helper (numpy / onnxruntime / tokenizers)
pip install "buildwithtrace-converter[vectorsearch]"
```

Pre-publish (private), install from git or a local checkout:

```bash
pip install "buildwithtrace-converter @ git+https://github.com/buildwithtrace/converter@main"
pip install -e ../converter   # local dev
```

## Usage

```python
from buildwithtrace_converter.eeschema.trace_parser import parse_trace_sch
from buildwithtrace_converter.eeschema.trace_json_to_sexp import trace_json_to_sexp
from buildwithtrace_converter.eeschema.sexp_to_trace_json import sexp_to_trace_json
from buildwithtrace_converter.pcbnew.trace_parser import parse_trace_pcb
```

The unified file CLI (used by the desktop via subprocess):

```bash
python -m buildwithtrace_converter.eeschema.trace IN OUT -f trace_sch -t kicad_sch
python -m buildwithtrace_converter.pcbnew.trace  IN OUT -f trace_pcb -t kicad_pcb
```

## Notes

- **Core is pure-stdlib** (no runtime dependencies). Only
  `common/local_vector_search.py` needs the `[vectorsearch]` extra, and the
  embedding model + tokenizer are NOT bundled — pass their paths in.
- **Source of truth.** Edit here. Consumers (`trace-cli`, `backend`, and later the
  `Trace` desktop) depend on this package; do not re-fork the sources.
- **Drift is enforced.** `scripts/verify_sync.py` diffs every shared converter source
  against the bundled copies and exits non-zero on drift. Run it locally after editing
  (it defaults to the sibling `trace-cli` + `Trace/trace` bundles):

  ```bash
  python3 scripts/verify_sync.py
  ```

  It is also a CI gate: the `converter-sync` job in `trace-cli/.github/workflows/ci.yml`
  clones this repo and checks the CLI bundle on every PR.
- **License:** see `LICENSE` (proprietary — distribute via a private index or git,
  not public PyPI).
