# LeafRoast

LeafRoast is a lightweight roast-profile manager for small-batch tea producers. It helps operators record batches, follow repeatable temperature profiles, track tasting notes, and export production history without requiring specialized cloud services.

> LeafRoast records and guides roasting workflows. It does not directly control roasting equipment or replace safe operating procedures.

## Features

- Create reusable roast profiles with timed temperature targets
- Record origin, cultivar, harvest date, moisture, and batch weight
- Run batches with step-by-step prompts and timers
- Compare planned and observed temperatures
- Attach operator notes and tasting results
- Export batch history as CSV or JSON
- Store data locally using SQLite
- Configure units, equipment, and batch-number formats

## Requirements

- Python 3.11 or newer
- SQLite 3
- A terminal with UTF-8 support

## Install

Clone the repository and create a virtual environment:

```bash
git clone https://github.com/example/leafroast.git
cd leafroast

python -m venv .venv
source .venv/bin/activate
```

On Windows, activate the environment with:

```powershell
.venv\Scripts\activate
```

Install the package:

```bash
pip install .
```

Initialize the local database and configuration:

```bash
leafroast init
```

## Usage

### Create a roast profile

```bash
leafroast profile add "Spring Green — Light" \
  --step "warm:90C:4m" \
  --step "roast:115C:7m" \
  --step "finish:95C:3m"
```

### List available profiles

```bash
leafroast profile list
```

### Start a batch

```bash
leafroast batch start \
  --profile "Spring Green — Light" \
  --lot LOT-2026-014 \
  --weight 2.5kg \
  --operator maya
```

During the roast, LeafRoast displays the current stage, elapsed time, target temperature, and prompts for observed temperatures. Press `Enter` to accept a prompt or use `n` to add a note.

### Review a completed batch

```bash
leafroast batch show TR-2026-0042
```

Add tasting notes after the tea has rested:

```bash
leafroast batch taste TR-2026-0042 \
  --score 86 \
  --notes "Toasted chestnut, sweet grass, clean finish"
```

### Export production records

```bash
leafroast export batches.csv --format csv --since 2026-01-01
```

Use `leafroast --help` or `leafroast <command> --help` for all available options.

## Configuration

LeafRoast creates `~/.config/leafroast/config.toml` by default. Set `LEAFROAST_CONFIG` to use a different file.

```toml
[roastery]
name = "North Field Tea Works"
timezone = "America/Toronto"
temperature_unit = "celsius"
weight_unit = "kilogram"

[batches]
number_format = "TR-{year}-{sequence:04d}"
default_operator = "maya"
require_lot_number = true

[equipment]
roaster_name = "Drum Roaster 5K"
capacity_kg = 5.0
temperature_tolerance_c = 3.0
sampling_interval_seconds = 60

[storage]
database = "./data/leafroast.sqlite3"
export_directory = "./exports"

[display]
color = true
audible_prompts = true
```

Environment variables override configuration-file values:

| Variable | Description | Default |
| --- | --- | --- |
| `LEAFROAST_CONFIG` | Path to the TOML configuration file | Platform config directory |
| `LEAFROAST_DATABASE` | Path to the SQLite database | `./data/leafroast.sqlite3` |
| `LEAFROAST_TIMEZONE` | IANA timezone used for batch timestamps | System timezone |
| `NO_COLOR` | Disable colored terminal output when set | Unset |

Relative storage paths are resolved from the directory containing the configuration file.

## Data and Backups

All production records are stored in the configured SQLite database. Back up the database regularly, especially before upgrades:

```bash
leafroast backup ./backups/leafroast-$(date +%Y-%m-%d).sqlite3
```

Do not edit the database directly while a roast session is active.

## License

MIT License. See `LICENSE` for details.