Metadata-Version: 2.4
Name: lanes-engine
Version: 2.0.0
Summary: Lanes Engine
Author: Lanes Wizard
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.20.0
Requires-Dist: premailer>=3.10.0
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🧙 LANES-ENGINE — Python CLI Orchestration Engine (v1.2.0)

`lanes-engine` is a terminal-native, highly parallel 15-lane email delivery engine written in Python leveraging `asyncio`. It divides massive recipient lists equally across 15 async workers executing concurrently in batches of 20 with live dashboard output, checkpoint-based resume controls, and **non-interactive** failure retry via `resend --failed-only`.

---

## 🎨 Visual Console Theme

```
    ✦  ·  ✧  ·  ✦  ·  ✧  ·  ✦
   ╔══════════════════════════════════════════════════════════════╗
   ║  ██╗      █████╗ ███╗   ██╗███████╗███████╗                 ║
   ║  ██║     ██╔══██╗████╗  ██║██╔════╝██╔════╝                 ║
   ║  ██║     ███████║██╔██╗ ██║█████╗  ███████╗                 ║
   ║  ██║     ██╔══██║██║╚██╗██║██╔══╝  ╚════██║                 ║
   ║  ███████╗██║  ██║██║ ╚████║███████╗███████║                 ║
   ║  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝                 ║
   ╚══════════════════════════════════════════════════════════════╝
       "We route the mail through chaos"
    ✧  ·  ✦  ·  ✧  ·  ✦  ·  ✧
```

* **24-bit gradient banner** (cyan → magenta, line-by-line)
* **Async typewriter** banner animation on cold start
* **Braille spinner** during session load + connection pre-warm
* **Hooded wizard ASCII mascot** drawn at start of every command
* **Per-lane live status glyphs** (◐ sending, ● done, ○ idle)
* **Confetti burst** when the campaign finishes

---

## 🚀 Core Features

1. **15 Parallel Async Lanes**: Distributes recipient lists equally across 15 lanes using an asynchronous round-robin queue.
2. **File-Driven Input**: Zero database requirements. Just drop `email.txt` and `senders.csv`.
3. **Live Dashboard Metrics**: Gradient progress bar, per-lane glyphs, processing speed, failure count.
4. **Auto-Retry (`resend --failed-only`)**: After any run, the engine writes `lanes-session.json` (template + recipients). Re-run failed emails non-interactively with one command.
5. **Fast Cold Start**: Backend connection pre-warmed in parallel with file parsing; `premailer` is lazy-loaded only when HTML mode is enabled.
6. **No Web Bloat**: Strictly a CLI engine built for speed.

---

## 📁 Input Format Requirements

### 1. `email.txt`
Place this in your working directory. Use `Subject:` as the first line header. Supports template rendering via `{{placeholder}}`:
```txt
Subject: Welcome {{name}} to Scholarly!

Hello {{name}},

Your journey through the lanes begins now.

— MQ Team
```

### 2. `senders.csv`
Contains the recipient email list and fields for templating:
```csv
email,name
alex@gmail.com,Alex
sara@gmail.com,Sara
john@gmail.com,John
```

---

## ⚙️ Installation & Commands

Install from PyPI:
```bash
pip install lanes-engine
```

### 1. Initialize Templates
Create initial `email.txt` and `senders.csv` mock templates in your current directory:
```bash
lanes-engine init
```

### 2. Run Campaign Processing
Parse the local templates and start the 15 parallel workers:
```bash
lanes-engine send
```

### 3. Check Latest Summary
Read the final log report from the latest run:
```bash
lanes-engine status
```

### 4. Open Detailed Performance Breakdown
Displays per-lane success/error counts and detailed failure stream error messages:
```bash
lanes-engine report
```

### 5. Auto-Resend Failed Emails (Non-Interactive)
Re-runs only the recipients that failed in the most recent session, using the saved `lanes-session.json`. No prompts, no interactive recycle loop:
```bash
lanes-engine resend --failed-only
```
You can chain `--no-banner` to skip the startup animation in CI/scripted environments:
```bash
lanes-engine resend --failed-only --no-banner
```

---

## 📄 License
MIT © Lanes Wizard
