# LeafBatch Roaster

LeafBatch Roaster is a lightweight batch planning and roast logging tool for small-batch tea roasting. It helps track green leaf inventory, roast profiles, tasting notes, finished-lot yields, and repeatable production settings for batches under 5 kg.

## Overview

This project is designed for tea studios, farmers, and small roasteries that need a simple way to record what happened during each roast without adopting a full manufacturing system.

LeafBatch focuses on practical day-to-day records:

- What tea was roasted
- Which profile was used
- Temperature and timing milestones
- Weight loss and final yield
- Operator notes and cupping results
- Lot traceability from raw leaf to finished product

## Features

- Create roast profiles for oolong, hojicha, black tea, green tea finishing, and custom styles
- Log batch weight, origin, harvest date, cultivar, and moisture notes
- Track roast stages such as warmup, charge, dry-down, aroma development, and finish
- Record temperature checkpoints and manual observations
- Calculate yield and moisture-loss percentage
- Maintain green-leaf and finished-tea inventory
- Export batch records as CSV or JSON
- Search past roasts by lot, profile, origin, or tasting note

## Install

### Requirements

- Python 3.11 or newer
- SQLite 3
- macOS, Linux, or Windows

### From source

```bash
git clone https://github.com/example/leafbatch-roaster.git
cd leafbatch-roaster
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

On Windows:

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e .
```

### Verify installation

```bash
leafbatch --version
```

## Usage

Initialize a local roastery database:

```bash
leafbatch init
```

Add a tea lot:

```bash
leafbatch lots add \
  --name "Spring Tieguanyin" \
  --origin "Anxi, Fujian" \
  --harvest "2026-04-18" \
  --cultivar "Tieguanyin" \
  --weight 12.5kg
```

Create a roast profile:

```bash
leafbatch profiles add hojicha-light \
  --tea-type green \
  --charge-temp 165C \
  --finish-temp 205C \
  --duration 14m
```

Log a batch:

```bash
leafbatch batches start \
  --lot "Spring Tieguanyin" \
  --profile hojicha-light \
  --input-weight 1.2kg \
  --operator "Mina"
```

Add roast events:

```bash
leafbatch batches event 42 --time 04:30 --temp 172C --note "grassiness fading"
leafbatch batches event 42 --time 09:15 --temp 193C --note "nutty aroma developing"
leafbatch batches finish 42 --output-weight 1.03kg --rating 8
```

View batch history:

```bash
leafbatch batches list
leafbatch batches show 42
```

Export records:

```bash
leafbatch export batches --format csv --output exports/july-roasts.csv
```

## Configuration

LeafBatch reads configuration from `leafbatch.toml` in the current directory, then from `~/.config/leafbatch/config.toml`.

Example:

```toml
[roastery]
name = "North Hill Tea Studio"
default_operator = "Mina"
timezone = "America/Toronto"

[database]
path = "./data/leafbatch.sqlite"

[units]
weight = "kg"
temperature = "C"

[roaster]
model = "RoastMaster 2K Drum"
max_batch_weight = 2.0
preheat_minutes = 18

[export]
default_format = "csv"
directory = "./exports"
```

Environment variables can override file-based configuration:

```bash
LEAFBATCH_DB_PATH=./data/production.sqlite
LEAFBATCH_DEFAULT_OPERATOR=Mina
LEAFBATCH_TEMPERATURE_UNIT=C
```

Common configuration options:

| Option | Description | Default |
| --- | --- | --- |
| `roastery.name` | Name shown in exports and reports | `LeafBatch Roastery` |
| `database.path` | SQLite database location | `./leafbatch.sqlite` |
| `units.weight` | Weight unit: `g`, `kg`, `oz`, or `lb` | `kg` |
| `units.temperature` | Temperature unit: `C` or `F` | `C` |
| `roaster.max_batch_weight` | Maximum recommended batch size | `2.0` |
| `export.directory` | Export output directory | `./exports` |