# Emberleaf

Emberleaf is a lightweight roast-profile manager for small-batch tea producers. It helps operators record batches, monitor temperature and airflow, save repeatable roast profiles, and export production logs for traceability.

Designed for tabletop electric roasters, Emberleaf can run in simulation mode or connect to supported serial temperature controllers.

## Features

- Live temperature, airflow, and elapsed-time monitoring
- Reusable roast profiles with timed operator prompts
- Batch records for origin, cultivar, harvest date, and lot number
- First-crack, aroma, color, and moisture observations
- Automatic roast-curve logging
- CSV and JSON exports
- Configurable temperature alarms and safety limits
- Simulation mode for training and profile development
- Local storage with no required cloud account

## Requirements

- Python 3.11 or later
- SQLite 3
- A serial-connected controller or simulation mode
- Linux, macOS, or Windows

## Install

Clone the repository and create a virtual environment:

```bash
git clone https://github.com/emberleaf/emberleaf.git
cd emberleaf

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

On Windows:

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

Install the package:

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

Initialize the local database:

```bash
emberleaf init
```

## Usage

Start Emberleaf in simulation mode:

```bash
emberleaf run --simulate
```

Start with a connected roaster:

```bash
emberleaf run --port /dev/ttyUSB0
```

On Windows, use the controller's COM port:

```powershell
emberleaf run --port COM3
```

Create a roast profile:

```bash
emberleaf profile create "Spring Green 01"
```

List available profiles:

```bash
emberleaf profile list
```

Begin a batch with a saved profile:

```bash
emberleaf batch start \
  --profile "Spring Green 01" \
  --lot "SG-2026-014" \
  --weight 2.5kg
```

Record an observation during the roast:

```bash
emberleaf batch note "Sweet chestnut aroma; leaf edges beginning to bronze"
```

Finish the active batch:

```bash
emberleaf batch finish --final-weight 2.31kg
```

Export production records:

```bash
emberleaf export --format csv --output exports/batches.csv
```

Run `emberleaf --help` or `emberleaf <command> --help` for all available options.

## Configuration

Emberleaf reads configuration from `emberleaf.toml` in the current directory. Generate a starter file with:

```bash
emberleaf config init
```

Example configuration:

```toml
[roaster]
name = "Workshop Roaster"
port = "/dev/ttyUSB0"
baud_rate = 115200
sample_interval_seconds = 1
maximum_temperature_c = 180
shutdown_temperature_c = 195

[batch]
default_weight_unit = "kg"
require_lot_number = true
require_operator = true

[storage]
database = "data/emberleaf.db"
export_directory = "exports"

[logging]
level = "INFO"
file = "logs/emberleaf.log"
retain_days = 30

[display]
temperature_unit = "celsius"
time_format = "24h"
```

Configuration values can be overridden with environment variables using the `EMBERLEAF_` prefix. Nested keys use double underscores:

```bash
export EMBERLEAF_ROASTER__PORT=/dev/ttyACM0
export EMBERLEAF_ROASTER__MAXIMUM_TEMPERATURE_C=175
export EMBERLEAF_LOGGING__LEVEL=DEBUG
```

Command-line options take precedence over environment variables and configuration-file values.

## Data and Backups

By default, batch records are stored in `data/emberleaf.db`. Back up this file regularly and before upgrading Emberleaf.

To create a timestamped backup:

```bash
emberleaf backup --output backups/
```

Roast logs contain production records but do not replace required food-safety documentation or calibrated equipment checks.

## License

Emberleaf is released under the MIT License.