# Local file automation reference

The fixed-version kit adds a batch runner, saved explicit CSV profiles, executable fixtures and a package manifest around the same engine used by the free tool. The free tool's build includes downloadable engine source. There is no exclusive algorithm, hosted customer-data API, account connector, cloud execution, custom onboarding or model call in the kit. Extra professional value depends on whether this packaging reduces a real repeated handoff in the buyer's workflow.

The examples below are buyer-owned automation. No scheduler, connector or CI service is installed by reading this document. Keep inputs, capabilities, private kit ZIPs and outputs out of public repositories. A buyer supplies its own execution environment and independently approved data. No external service is required for calculation.

## Reproduce one real file job

Download the helper [run_files.py](integration-examples/run_files.py), then run it with an extracted kit and a supported file folder:

```sh
python3 run_files.py /absolute/kit/product.py /absolute/kit/samples/file-input /absolute/new-result
```

It uses the documented local `files_to_payload`, `run` and `bundle` APIs. This helper is an openly available integration example, not an additional paid entitlement. The kit contains its own `batch.py` for multiple jobs.

## Batch contract

From the extracted kit, make `jobs/example/` and copy `samples/file-input/*` into it. Run:

```sh
python3 batch.py jobs results-001
```

The batch runner accepts 1–200 regular immediate job directories, with no symlinks. Original input is bounded to 32 MiB per job and per file. Every engine has its own tighter format/row/pixel limits; the intersection applies. An engine process has a 45-second deadline. `output` must be a new directory disjoint from `input`. An existing result is never replaced by the batch runner. Native single-job CLI overwrite rules differ by product, so use a new folder there too.

`batch-report.json` schema version 1 contains `engine_sha256`, `profiles`, `status`, and `jobs`. Each job has original directory name in `job`, generated `output` directory, and `status`. When available it also has `input_sha256`, `exit_code`, `result_sha256`; failure/unavailability can add `reason`. Per-job directories contain `report.json` and, for accepted PASS/UNKNOWN computations, `result.zip`. A caught input/profile problem may have only its receipt row. The top-level result is FAIL when any job is FAIL, otherwise UNKNOWN when any job is UNKNOWN, otherwise PASS. Retain every row; do not infer that a top-level FAIL erased another job's known evidence.

Exit 0 = PASS, 2 = FAIL and 3 = UNKNOWN. Timeouts, missing engine evidence and unavailable processes produce UNKNOWN job results. A wrapper-level argument/setup failure exits 2. Scheduling failure without a receipt is UNKNOWN operational evidence; never count it as an empty successful period.

## Buyer-owned scheduling

[scheduled_run.py](integration-examples/scheduled_run.py) creates a fresh timestamp-and-random run directory and invokes the kit runner. It is a local example, not a daemon or unattended fleet change:

```sh
python3 scheduled_run.py /absolute/kit /absolute/jobs /absolute/run-history
```

After reviewing these paths, a buyer may invoke that exact command from its existing scheduler or task runner. Inputs must be a stable snapshot before a run begins; publish each snapshot folder atomically from the upstream exporter and avoid editing it during a run. Keep schedules from overlapping. Preserve exit code, stderr and `batch-report.json` in the buyer's own monitoring. Review UNKNOWN/FAIL before promoting a result; do not retry indefinitely or treat an absent receipt as success. No automatic emails, payments or external writes are part of the example.

## CI and byte reproducibility

Use an existing private local CI runner with Python 3.12+ and the pinned dependencies if supplied. Acquire dependencies separately in the buyer's approved environment; these examples install nothing. Fetch no customer data in CI. Use synthetic fixtures and compare the exact kit first:

```sh
python3 verify_replay.py /absolute/kit
```

[verify_replay.py](integration-examples/verify_replay.py) validates each actual kit member against `KIT-MANIFEST.json`, refuses unexpected files other than Python bytecode caches, copies the supplied file fixture into a temporary job, runs the bundled batch CLI twice and compares the actual result ZIP hashes. An input/status error or byte mismatch is not accepted. This verifies same-environment replay of the supplied example; it does not prove all real files, arbitrary dependency upgrades or all platform combinations. Do not commit generated customer results. Run the kit's `test_*.py` suite separately when changing its code or environment.

## Cross-tool boundaries

These five engines have different domain identities. There is no supported automatic output-to-input chain between them. Combining a linen movement count with royalty receipts, or a specimen mosaic with assay intervals, would require an independently supplied relationship and is not a feature. Useful combinations are each engine plus the buyer's existing export source, its private scheduler/CI and its downstream review tools, using the exact CSV/PNG/JSON boundary in the product reference. CSV import into a spreadsheet does not prove compatibility with a named vendor. The local Python API examples avoid an invented integration marketplace or another execution platform.

## Operational value measurement

Measure the same supported job with the existing method and the kit: preparation minutes, review minutes, correction minutes, repeat runs and excluded/UNKNOWN results. Total buyer time includes mapping and troubleshooting. Record the actual difference only after both outputs have been independently reviewed. A hypothetical hourly rate is an assumption, not measured revenue or savings. Break-even jobs = total purchase/setup cost divided by positive observed cost saving per job; when the denominator is zero or unknown, break-even is UNKNOWN. No savings or ROI is established by the synthetic examples.