Metadata-Version: 2.4
Name: labparse
Version: 0.1.0
Summary: One parser for lab instrument exports: plate readers, spectrometers, and any format your own LLM can learn once and cache forever.
Author-email: Paul Crinigan <paul@aiappsapi.com>
License: MIT
Project-URL: Homepage, https://www.learnhowtoscience.com
Project-URL: Author, https://www.aiappsapi.com
Keywords: plate-reader,spectrometer,instrument,parser,lab,tecan,spectramax,tidy-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.4
Provides-Extra: excel
Requires-Dist: openpyxl>=3.0; extra == "excel"
Dynamic: license-file

# labparse

One parser for lab instrument exports. Point it at the file your plate reader, spectrometer, or other bench instrument spat out, and get back a tidy table: one row per reading, with well, row, column, cycle, time in seconds, and value.

```python
import labparse

result = labparse.parse("growth.asc")
result.data            # tidy pandas DataFrame
result.wide()          # one column per well
result.save_csv("tidy.csv")
```

```
labparse growth.asc --out tidy.csv
labparse kinetic.txt --wide
```

## The trick: formats are learned once, then free forever

Every instrument exports its own hostile format, and most labs end up writing throwaway parsing scripts for each one. labparse works differently:

1. Known formats parse instantly using bundled recipes, small JSON descriptions of a format that a deterministic engine executes.
2. When labparse meets a format it does not know, it shows the raw file to your own LLM once, and the LLM writes a new recipe.
3. The recipe is only accepted if it actually parses your file. A wrong recipe is rejected and retried, it can never silently produce bad data.
4. Accepted recipes are cached in `~/.labparse/recipes`, so each format costs at most one LLM call ever, and cached formats parse offline.

No LLM configured? Everything with a bundled or cached recipe still works, unknown formats give a clear message instead.

## Bundled formats

- Tecan plate reader ASCII exports (`.asc`, repeated well grids)
- Molecular Devices SoftMax Pro / SpectraMax kinetic exports (`.txt`)
- Generic wide tables, CSV or TSV, with one column per well
- Generic long tables, CSV, with a well column and a value column
- Excel workbooks containing a well header row or a plate grid (`pip install labparse[excel]`)

Recipes are plain JSON. You can read them, edit them, share them with your lab, and drop new ones into the recipe folder. `labparse --list-recipes` shows everything installed.

## Bring your own model (for learning new formats)

labparse looks for a language model in this order and uses the first one it finds:

1. `claude` CLI (an active Claude Code login)
2. `codex` CLI
3. `ANTHROPIC_API_KEY`
4. `OPENAI_API_KEY` (set `OPENAI_BASE_URL` for any OpenAI compatible server)

Control it with `--llm off`, `--llm claude`, or the `LABPARSE_LLM` environment variable.

## Install

```
pip install labparse
```

Excel support: `pip install labparse[excel]`

## Output columns

| column | meaning |
|---|---|
| well | normalized well id, `A1` to `P24` |
| row | plate row letter |
| col | plate column number |
| cycle | reading number in file order, starts at 1 |
| time_s | seconds, parsed from `h:mm:ss` or numeric time fields, NaN when the format has no time |
| value | the measurement |

Extra columns from the instrument, like temperature, are kept.

## Author

Built by [Paul Crinigan, AI Apps API](https://www.aiappsapi.com). Part of the free science tools collection at [learnhowtoscience.com](https://www.learnhowtoscience.com).

MIT licensed.
