Metadata-Version: 2.5
Name: jitxlib-parts
Version: 2.0.0
Summary: Pluggable parts database and search interface for JITX
Project-URL: Homepage, https://jitx.com
Project-URL: Documentation, https://docs.jitx.com
Author: JITX
Maintainer: JITX
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Requires-Dist: jitx<5,>=4.6.0
Requires-Dist: jitxlib-standard<5,>=4.6.0
Description-Content-Type: text/markdown

# jitxlib-parts

A pluggable parts database and search interface for JITX.

Describe a passive by what it has to do; the provider chain decides which part
satisfies it.

```python
from jitx.circuit import Circuit
from jitx.units import kohm, pct, uF, V
from jitxlib.parts import AtLeast, AtMost, Capacitor, Resistor

class Divider(Circuit):
    def __init__(self):
        self.top = Resistor(resistance=10 * kohm, tolerance=AtMost(1 * pct))
        self.bottom = Resistor(resistance=4.7 * kohm, tolerance=AtMost(1 * pct))
        self.bypass = Capacitor(capacitance=1 * uF, rated_voltage_dc=AtLeast(10 * V))

        self.nets = [
            self.top.p2 + self.bottom.p1,
            self.bypass.p1 + self.top.p1,
        ]
```

`Resistor`, `Capacitor`, `PolarizedCapacitor` and `Inductor` are ordinary
`jitx.Component` subclasses with their ports already declared: `p1`/`p2`, or
`a`/`c` for `PolarizedCapacitor`. Resolution happens at the end of elaboration,
or earlier if you read a resolved field.

`examples/sensor-frontend` is a complete project you can copy.

## Configuring where parts come from

Providers are asked in order, first hit wins.

```toml
[tool.jitx.parts]
chain = ["csv:parts/approved-parts.csv", "ideal"]
lock = "parts.lock.json"
lock-mode = "read-write"
```

`csv:` reads a CSV of approved parts; everything after the colon is a path
relative to `pyproject.toml`. `ideal` synthesizes a part at whatever value was
asked for, so a design elaborates before anyone has approved a real one — its
parts carry no manufacturer, which is how you tell they are not orderable.
Values snap to the E-series a part of the synthesized tolerance comes in (1%
unless the query pins one, which allows E24 and E96 values; 5% allows E24
only). `ideal:E96`, or several joined as `ideal:E24+E96`, fixes the series
instead.

A chain can also be set in Python, and scoped:

```python
from jitxlib.parts import PartSource
from jitxlib.parts.providers import CsvParts, IdealPassives

class Board(Design):
    parts = PartSource([CsvParts("parts/approved.csv"), IdealPassives()])

    def __init__(self):
        with PartSource([CsvParts("parts/mil-spec.csv")]):
            self.rf = RfFrontend()      # resolves against the mil-spec list
```

Precedence, highest first: a `with PartSource(...)` block, a `parts` attribute on
the `Design`, `[tool.jitx.parts] chain`, a chain published by an installed
package, and — only with `discover = true` — a guess from installed providers.
Configure none of them and you get an error listing these options rather than a
guess.

### A shared catalogue in a package

An approved-parts list used across several projects belongs in a pip package,
named as a resource rather than a path:

```python
CsvParts.from_package("acme_parts", "approved.csv")
```

Publish a chain from that package and any project installing it picks it up:

```toml
[project.entry-points.jitxlib-parts-policy]
acme = "acme_parts.chain:chain"
```

## The CSV format

The header is the vocabulary. `category`, `mpn` and `manufacturer` are identity,
`datasheet` is reported but not queryable, and every other column becomes a
queryable attribute under its own name. Every one of them is readable on the
resolved component, so `r.tolerance` and `r.datasheet` both work.

```csv
category,mpn,manufacturer,resistance,case,tolerance,price
resistor,RC0402FR-0710KL,Yageo,10000,0402,0.01,0.0032
resistor,ERA-2AEB103X,Panasonic,10 kohm,0402,0.001,0.0900
```

A dimensioned column takes a bare number or one carrying its own unit. A bare
number gets an engineering prefix, so it reads as `10 kΩ` rather than `10000 Ω`;
a written unit is used as written. Add a `stock` column and
`rank=Maximize("stock")` starts working, with no code change.

## Queries

Field values are predicates. Bare values and tuples coerce, so the simple cases
stay simple.

| | |
| --- | --- |
| `resistance=10 * kohm` | `Exactly` |
| `case=("0402", "0603")` | `OneOf` |
| `tolerance=AtMost(1 * pct)` | `Range`, one-sided |
| `resistance=Range(9 * kohm, 11 * kohm)` | closed interval |
| `resistance=Tolerance.percent(10 * kohm, 1)` | typical with bounds |
| `tcr=Exists(True)` | the attribute is present |

Dimensioned values carry their units, and equivalent spellings are the same
query: `10 * kohm` and `10000 * ohm` match the same parts and share a lockfile
entry.

`rank=` orders the matches rather than filtering them, applied
lexicographically:

```python
Resistor(resistance=10 * kohm, rank=(Minimize("area"), Minimize("price")))
```

Anything the core does not name goes to the providers as-is, so a
provider-specific attribute needs no ceremony:

```python
Resistor(resistance=10 * kohm, aec_q200=True, lcsc="C25744")
```

Building a query object directly, the constructor takes the named fields; add
anything else with `update`:

```python
ResistorQuery(resistance=10 * kohm).update(lcsc="C25744")
```

A query can be set on a `Design` or a `Circuit` and is inherited by everything
below it:

```python
class Board(Design):
    shared = ResistorQuery(case=Exactly("0402"), tolerance=AtMost(1 * pct))
```

## The lockfile

The first run records which part answered which query; later runs replay it, so
the board does not move when a catalogue gains rows. It is written at the end of
elaboration and belongs in version control.

| mode | behaviour |
| --- | --- |
| `read-write` | default: replays what it has, resolves and records the rest |
| `read` | replay; a query the lock cannot answer fails the run at the end |
| `check` | run normally, then resolve cleanly and report where the board differs |
| `replay` | hermetic: replay and adopt only, never resolve; a miss fails the run |
| `off` | ignore the lockfile |

How much each mode asks the chain differs, and it is the main thing to know:

- `read` resolves only what the lock cannot answer -- loudly, and reported per
  query, so the board is complete and the report is too.
- `check` runs normally and then resolves the whole design cleanly, reporting
  where the board it built differs from what that clean run would build. It costs
  a second full set of provider calls, which is why it is something to run in CI
  rather than on every build. The ordinary run's part is the one that gets built,
  so a `check` run builds what a `read` run would and the comparison is pure
  reporting.

  Every bound part is compared, adoptions included. An adoption is decided from
  the lockfile alone, so it says nothing about what a clean resolve of the
  re-keyed query would return -- it supplies a baseline for a query the lock could
  not key, and whether the clean run agrees is then a real question. Often it
  does; when it does not, the board holds a part a from-scratch run would not
  choose, which is what this mode exists to report.

  To run it without touching the project's configured mode, use the
  `parts-check` exporter. It runs the design under `check` whatever its lock says,
  and prints the report, or writes it with `--output`. Each `differs` line names
  where the component was constructed. The export succeeds regardless unless
  `--fail` names report categories to fail on; it may be repeated, and
  `--fail all` fails on any of them:

  ```
  $ jitx design export parts-check my_board.MyDesign --output parts-check.txt
  $ jitx design export parts-check my_board.MyDesign --fail differs
  ```
- `replay` resolves nothing at all. It asks the chain no questions, so it runs on
  a box with no catalogue or credentials.

Adoption works in every pinned mode, `replay` included, because it reaches its
decision from the lockfile and rebuilds what it adopted locally.

A chain that cannot be reached is recorded as `unresolvable` rather than raised,
in every mode, so a run that cannot resolve still reports what is unpinned
instead of dying mid-elaboration.

`lock-mode` is unset by default, which means `read-write`. A value that does not
name a mode logs a warning and falls back to `read`: a typo should not silently
re-pin the design, and should not stop a build the lock can answer either.

Editing a query does not churn the parts you did not touch. If the part already
chosen still satisfies the edited query it is kept, and the entry records what it
was adopted from.

Use `lock_scope` when two identical queries should be pinned separately:

```python
Resistor(resistance=10 * kohm, lock_scope="rf")
```

## Exploring

For a script, a REPL or a notebook. These take an explicit `source` and return
parts rather than components, so nothing is added to a design.

```python
from itertools import chain

from jitxlib.parts import PartSource, distinct, explain, search
from jitxlib.parts.providers import CsvParts

source = PartSource([CsvParts("parts/approved-parts.csv")])
found = search(ResistorQuery(resistance=10 * kohm), limit=20, source=source)

# Grouped, which is usually the point: which catalogue had what.
for member, parts in found.items():
    for part in parts:
        print(member, part.identity.mpn, part.identity.attributes)

# Or flat, still in chain order, when the grouping does not matter.
for part in chain.from_iterable(found.values()):
    print(part.identity.mpn)

print(explain(CapacitorQuery(capacitance=22 * uF), source=source))
print(distinct(CapacitorQuery(case="0402"), "rated_voltage_dc", source=source))
```

`explain` shows the chain in order with each provider's own reason, which is the
quickest way to find out why nothing matched.

`search` gathers candidates along the chain until it has the `limit` asked for,
rather than stopping at the first member with anything: precedence decides which
part gets *selected*, but a request for twenty is not answered by the three the
first catalogue happened to hold.

It is keyed by the member that offered each part, in chain order, because which
catalogue has a part is usually the thing being asked -- and that is not
recoverable from the part itself, since `identity.provider` is the provider's own
name, which two members can share and a delegating provider gets wrong. A member
that was asked and had nothing is present with an empty list; one the walk never
reached, because the limit filled first, is absent. Nothing is compared across
members. A provider that vetoes the query stops the walk and raises `PartDenied`.

Nothing here is cached, so asking twice asks twice. Inside a design, omitting
`source` discovers the project's chain rather than the one in force -- pass
`source=PartSource.get()` for that.

## Writing a provider

Subclass `Provider`, or `CategoryProvider` to answer one query at a time.
`jitxlib.parts.provider` re-exports everything you need.

```python
from dataclasses import dataclass
from jitxlib.parts.provider import (
    JSON, CanonicalQuery, CategoryProvider, NoMatch, Outcome, PartIdentity,
    ResolvedPart, Unsupported, match, rank_by,
)

@dataclass(frozen=True)
class AcmePlm(CategoryProvider):
    base_url: str
    name: str = "acme-plm"

    def config(self) -> dict[str, JSON]:
        # Anything that could change which part gets selected. Must be stable
        # across runs and machines; it identifies the chain in the lockfile.
        return {"base_url": self.base_url}

    def resolve_one(self, query: CanonicalQuery) -> Outcome:
        # Resolved(parts), best first; NoMatch if you have nothing, Unsupported
        # if you cannot answer this query at all.
        ...

    def rehydrate(
        self, identity: PartIdentity, payload: dict[str, JSON]
    ) -> ResolvedPart:
        # Rebuild a part from a lockfile entry you wrote. Raise StalePayload if
        # the payload predates a change you cannot honour.
        ...
```

Attributes are for selection and the payload is for everything else. Putting a
key in `attributes` promises the provider will filter and rank on it, so a value
a remote catalogue reports but will not accept as a query term, or one that goes
stale between runs, belongs in the payload and is set on the component in
`materialize`. The core sets attributes on the component itself, so both are
readable either way.

A payload is stored in the lockfile verbatim, so it must be JSON: a quantity in
there fails the write. `encode_payload` renders one and `decode_payload` reads it
back, using the same encoding as part attributes.

Override `resolve(batch)` instead of `resolve_one` to see many queries at once.
Duplicate requests are collapsed into one query -- a hundred identical caps must
not become a hundred catalogue scans -- so how many components asked is carried
on `CanonicalQuery.count` rather than by repetition. It is demand, not a
constraint: it takes no part in matching or the digest, and ignoring it is
correct.

**A batch is not the design, and a provider doing whole-batch optimization has to
be written knowing that.** A provider receives the complete set of queries only
when every one of them is new: a first run against an empty lock, or `off` mode.
Under `read` and `read-write` a query the lock can answer never reaches the chain,
so against a populated lockfile the batch is the *unpinned remainder* -- on a
clean second run, nothing at all. `replay` never calls a provider to resolve.
Batching is best effort on top of that, so an early flush splits one elaboration
across several batches.

`check` is the exception and always asks twice: once for the ordinary run, over
the unpinned remainder, which is what it builds, and once over every query the
design asked, which is the clean run it compares the board against. That second
call is the whole order, so a provider is asked the same question a from-scratch
run would ask, rather than being handed a fragment and blamed for answering it
differently.

That matters for anything order-wide: minimum order quantities, bulk rebates,
consolidating a reel, allocation across sources. Those are properties of the whole
order, and the batch is the whole order only on a run where nothing is pinned. The
tension is inherent rather than a gap to be closed -- if a selection depends on the
order, adding one component can legitimately move every selection, which is what a
lock exists to prevent. A provider that makes that trade owns it.

`config`, `resolve` and `rehydrate` are required; `distinct` and
`discovery_priority` are optional. A frozen dataclass is the recommended form,
since two providers configured the same way should be interchangeable. Give
`name` as a field or a plain attribute rather than a `property`, and for a
derived one use `field(init=False)` set in `__post_init__`.

`materialize` must not construct a part that itself resolves through a chain; it
runs while parts are binding, and doing so raises `NestedDeferral`. Build such a
part in the owning circuit and hand it over, or give the provider concrete
geometry.

A chain member is addressed by name -- that is what a lockfile entry records and
what replay looks up. A member takes its provider's own name, and two that collide
are suffixed positionally (`acme`, `acme#2`). That works but says nothing about
which is which, and moves if the chain is reordered, so name them instead:

```python
from jitxlib.parts import Named, PartSource

PartSource([
    Named("approved", AcmeParts(APPROVED_DSN)),
    Named("fallback", AcmeParts(FALLBACK_DSN)),
])
```

A member's name is part of the chain's identity, so renaming one re-keys the
chain and its entries re-resolve once, like any other chain edit.

Register it so a chain can name it as a string:

```toml
[project.entry-points.jitxlib-parts-provider]
acme-plm = "acme_plm.provider:AcmePlm"
```

`src/jitxlib/parts/providers/` has two worked examples: `CsvParts` searches a
file, `IdealPassives` synthesizes.

## Development

```console
$ hatch test
$ hatch fmt --check
$ hatch run types:check
```
