Metadata-Version: 2.4
Name: matchplan
Version: 0.2.0
Summary: Choose how to match records: a run plan, what may be claimed, and repairs if the setup is dirty.
Author: Nikita N. Kadochnikov
License: CC-BY-NC-SA-4.0
Keywords: entity-matching,record-linkage,evaluation-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# matchplan

Choose how to match two record lists. The package writes a run plan, what may be claimed, and repairs if a setup is provided and dirty. It does not merge the lists and does not invent quality scores.

License: [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). Research and personal use are allowed. Commercial use is not.

## Install

```bash
pip install matchplan
```

From this directory (development):

```bash
pip install -e .
```

Tests must see this tree, not a previously installed copy:

```bash
python -m unittest discover -s tests
```

(`tests/__init__.py` puts `src` first on `sys.path`.)

## Fields

1. `goal` — `prod` or `research`
2. `what` — what to match, in the caller's words
3. Limits — `max-labels`, optional `max-usd`, optional `min-quality`
4. Optional `claim` — `zero_label` / `prompt_only` / `few_examples` / `labeled` / `transfer`
5. Optional setup file — how labels were used

If `min-quality` is set, the package cannot check it without computed scores. It writes a 50-pair pilot procedure instead of pretending the slots are scored.

## Commands

```bash
matchplan run --goal prod --what "two product price lists" --out ./out --max-labels 0
```

```bash
matchplan check --setup setup.json --out ./out
```

```bash
matchplan run --goal research --what "two catalogs" --setup setup.json --out ./out --prereg
```

`--out` gets `report.md`, `plan.json`, and `card.json`. Scores that were not computed are marked as not scored. Repair runs only when `--setup` is given.

To run a recommended regime with **your** model (optional; does not rewrite `card.json` and does not merge lists):

```bash
matchplan execute --out ./out --endpoint https://your-model.example/v1 --key-env YOUR_API_KEY --pairs pairs.json
```

Without `--pairs`, `execute.json` only restates the selection procedure.

Worked evaluation examples are not shipped in this package.

## For agents

1. Call this package. Do not invent F1 or cost.
2. Fill the fields. Ask only if a required field is missing.
3. If the caller described a label budget, write `setup.json` and pass `--setup`.
4. Return the package output. Do not replace it with a free-text guess.
