letz-cli 0.1.0__tar.gz

letz_cli-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+dist/
+__pycache__/
+*.egg-info/
+letz_work/

letz_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Letz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

letz_cli-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: letz-cli
+Version: 0.1.0
+Summary: Letz Brain CLI - pull campaigns from the Letz platform, draft email sequences locally with Claude, and push them back staged for review.
+Project-URL: Homepage, https://sam.weareletz.com
+Author: Letz
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,email,letz,outreach,sdr,sequences
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Other Audience
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Letz Brain CLI
+
+Generate email sequences **off-platform** (on flat-rate Claude compute), push them to
+the [Letz](https://sam.weareletz.com) platform staged for review, and let the cloud
+**just click send**. Zero cloud AI cost.
+
+## Why
+
+Every time the cloud app composes a sequence it spends metered AI money. This CLI moves
+all of that generation onto your own Claude subscription. The platform only renders the
+finished drafts for review and sends them when a human clicks **Activate**.
+
+## Install
+
+Requires Python 3.10+. No other dependencies (pure standard library).
+
+```bash
+pip install letz-cli
+# or, in a managed Python environment:
+pipx install letz-cli
+```
+
+Then point it at your Letz platform:
+
+```bash
+export LETZ_API_URL="https://your-letz-instance.example.com"
+```
+
+## Workflow
+
+```bash
+# 1. Pull a campaign's config + leads. Writes letz_work/<id>.pull.json and a
+#    letz_work/<id>.ready.json scaffold (one entry per lead, empty emails).
+letz pull <campaign_id>
+
+# 2. GENERATION happens HERE: fill the "emails" arrays in letz_work/<id>.ready.json.
+#    In an interactive Claude session, Claude writes the sequences directly into that
+#    file, following the campaign's style guide + brand persona. Run this step on a
+#    subscription-auth Claude session — not a metered API key — or the cost saving
+#    is lost.
+
+# 3. Quality gate (pure Python, no AI). Fails on em dashes, spam phrases, forbidden
+#    names, over-length, etc.
+letz check <campaign_id>
+
+# 4. Push staged (PAUSED — nothing sends). Idempotent.
+letz push <campaign_id>
+
+# 5. Review the drafts in the platform UI (campaign detail → previews), then click
+#    Activate. Or release from the CLI:
+letz push <campaign_id> --activate   # flips campaign active → sending begins in-window
+
+# Inspect anytime:
+letz status <campaign_id>
+```
+
+## Commands
+
+| Command | What it does | AI? |
+|---|---|---|
+| `pull <id>` | fetch campaign + persona + leads → pull.json + ready.json scaffold | no |
+| `check <id>` | run the deterministic quality gauntlet on ready.json | no |
+| `push <id>` | import drafts, staged paused; re-runs the gauntlet first | no |
+| `push <id> --activate` | push **and** flip the campaign active (begins sending) | no |
+| `status <id>` | staged enrollments / previews / sends | no |
+
+Flags: `--api <url>` (or `$LETZ_API_URL`), `--work <dir>` (or `$LETZ_WORK`, default `./letz_work`).
+
+## Safety
+
+- The CLI talks only to the platform's REST API. Pushing drafts can never trigger a
+  send by itself.
+- `push` stages **paused** by default and re-runs the gauntlet; it refuses hard-failing
+  content unless `--force`.
+- Only `--activate` (or a human clicking Activate) ever causes a send.

letz_cli-0.1.0/README.md

@@ -0,0 +1,75 @@
+# Letz Brain CLI
+
+Generate email sequences **off-platform** (on flat-rate Claude compute), push them to
+the [Letz](https://sam.weareletz.com) platform staged for review, and let the cloud
+**just click send**. Zero cloud AI cost.
+
+## Why
+
+Every time the cloud app composes a sequence it spends metered AI money. This CLI moves
+all of that generation onto your own Claude subscription. The platform only renders the
+finished drafts for review and sends them when a human clicks **Activate**.
+
+## Install
+
+Requires Python 3.10+. No other dependencies (pure standard library).
+
+```bash
+pip install letz-cli
+# or, in a managed Python environment:
+pipx install letz-cli
+```
+
+Then point it at your Letz platform:
+
+```bash
+export LETZ_API_URL="https://your-letz-instance.example.com"
+```
+
+## Workflow
+
+```bash
+# 1. Pull a campaign's config + leads. Writes letz_work/<id>.pull.json and a
+#    letz_work/<id>.ready.json scaffold (one entry per lead, empty emails).
+letz pull <campaign_id>
+
+# 2. GENERATION happens HERE: fill the "emails" arrays in letz_work/<id>.ready.json.
+#    In an interactive Claude session, Claude writes the sequences directly into that
+#    file, following the campaign's style guide + brand persona. Run this step on a
+#    subscription-auth Claude session — not a metered API key — or the cost saving
+#    is lost.
+
+# 3. Quality gate (pure Python, no AI). Fails on em dashes, spam phrases, forbidden
+#    names, over-length, etc.
+letz check <campaign_id>
+
+# 4. Push staged (PAUSED — nothing sends). Idempotent.
+letz push <campaign_id>
+
+# 5. Review the drafts in the platform UI (campaign detail → previews), then click
+#    Activate. Or release from the CLI:
+letz push <campaign_id> --activate   # flips campaign active → sending begins in-window
+
+# Inspect anytime:
+letz status <campaign_id>
+```
+
+## Commands
+
+| Command | What it does | AI? |
+|---|---|---|
+| `pull <id>` | fetch campaign + persona + leads → pull.json + ready.json scaffold | no |
+| `check <id>` | run the deterministic quality gauntlet on ready.json | no |
+| `push <id>` | import drafts, staged paused; re-runs the gauntlet first | no |
+| `push <id> --activate` | push **and** flip the campaign active (begins sending) | no |
+| `status <id>` | staged enrollments / previews / sends | no |
+
+Flags: `--api <url>` (or `$LETZ_API_URL`), `--work <dir>` (or `$LETZ_WORK`, default `./letz_work`).
+
+## Safety
+
+- The CLI talks only to the platform's REST API. Pushing drafts can never trigger a
+  send by itself.
+- `push` stages **paused** by default and re-runs the gauntlet; it refuses hard-failing
+  content unless `--force`.
+- Only `--activate` (or a human clicking Activate) ever causes a send.

letz_cli-0.1.0/letz/__init__.py

@@ -0,0 +1,5 @@
+"""Letz Brain CLI — pull a campaign from the Letz platform, draft email
+sequences locally with Claude, and push them back staged for review.
+Nothing sends until a human clicks Activate.
+"""
+__version__ = "0.1.0"

letz_cli-0.1.0/letz/__main__.py

@@ -0,0 +1,246 @@
+"""Letz Brain CLI entrypoint.
+
+Workflow:
+    letz pull <campaign_id>        # fetch campaign + persona + leads -> work/<id>.pull.json
+                                   #   (also writes a work/<id>.ready.json scaffold to fill)
+    # --- generation happens HERE (Claude fills work/<id>.ready.json) ---
+    letz check <campaign_id>       # run the pure-Python quality gauntlet (no AI)
+    letz push <campaign_id>        # POST /sequences/import, staged PAUSED (no send)
+    letz status <campaign_id>      # show staged enrollments / previews / sends
+    # review in the UI, then click Activate (or: letz push --activate)
+
+Config:
+    --api   base URL (default: $LETZ_API_URL or http://localhost:8000)
+    --work  work dir (default: $LETZ_WORK or ./letz_work)
+"""
+from __future__ import annotations
+import argparse
+import datetime
+import json
+import os
+import sys
+
+try:
+    from .api import LetzAPI, LetzAPIError
+    from .gauntlet import audit_sequence
+except ImportError:  # allow running as a plain script: python cli/letz/__main__.py
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from letz.api import LetzAPI, LetzAPIError
+    from letz.gauntlet import audit_sequence
+
+
+def _work_dir(args) -> str:
+    d = args.work or os.environ.get("LETZ_WORK") or os.path.join(os.getcwd(), "letz_work")
+    os.makedirs(d, exist_ok=True)
+    return d
+
+
+def _pull_path(args, cid): return os.path.join(_work_dir(args), f"{cid}.pull.json")
+def _ready_path(args, cid): return os.path.join(_work_dir(args), f"{cid}.ready.json")
+
+
+def _load(path):
+    with open(path) as f:
+        return json.load(f)
+
+
+def _save(path, obj):
+    with open(path, "w") as f:
+        json.dump(obj, f, indent=2, ensure_ascii=False)
+
+
+# ---------------------------------------------------------------- commands ----
+def cmd_pull(args):
+    api = LetzAPI(args.api)
+    camp = api.campaign(args.campaign_id)
+    if not camp:
+        print(f"✗ Campaign {args.campaign_id} not found at {args.api}")
+        return 2
+    persona = api.persona()
+    leads = api.leads(args.campaign_id, limit=args.limit)
+    pull = {
+        "pulled_at": datetime.datetime.utcnow().isoformat() + "Z",
+        "api": args.api,
+        "campaign": camp,
+        "persona": persona,
+        "leads": leads,
+    }
+    _save(_pull_path(args, args.campaign_id), pull)
+
+    # Auto-write a ready.json scaffold to fill in.
+    forbidden = persona.get("forbidden_names", "") if persona else ""
+    scaffold = {
+        "campaign_id": camp["id"],
+        "campaign_name": camp.get("name", ""),
+        "max_touches": camp.get("max_touches", 3),
+        "touch_intervals": camp.get("touch_intervals", []),
+        "forbidden_names": forbidden,
+        "_style_guide": camp.get("style_guide", ""),
+        "_strategy_brief": camp.get("strategy_brief", ""),
+        "_tone": camp.get("tone", "professional"),
+        "_from_name": camp.get("from_name", "Sam Reyes"),
+        "sequences": [
+            {
+                "lead_id": l.get("id"),
+                "_lead": {
+                    "name": (l.get("first_name", "") + " " + l.get("last_name", "")).strip(),
+                    "title": l.get("title", ""), "company": l.get("company", ""),
+                    "industry": l.get("industry", ""), "email": l.get("email", ""),
+                },
+                "brief": {},
+                "emails": [],
+            }
+            for l in leads if l.get("id") and (l.get("email") or "").strip()
+        ],
+    }
+    # Don't clobber an in-progress ready file unless --force.
+    rp = _ready_path(args, args.campaign_id)
+    if os.path.exists(rp) and not args.force:
+        print(f"• ready scaffold already exists (kept): {rp}  (use --force to overwrite)")
+    else:
+        _save(rp, scaffold)
+        print(f"✓ scaffold written: {rp}")
+
+    n_with_email = len(scaffold["sequences"])
+    print(f"✓ pulled '{camp.get('name')}' — {len(leads)} leads ({n_with_email} with email) -> {_pull_path(args, args.campaign_id)}")
+    print(f"  Next: fill the 'emails' arrays in {rp} ({camp.get('max_touches',3)} touches each), then `letz check {args.campaign_id}`")
+    return 0
+
+
+def cmd_check(args):
+    ready = _load(_ready_path(args, args.campaign_id))
+    forbidden = ready.get("forbidden_names", "")
+    expected = ready.get("max_touches")
+    seqs = ready.get("sequences", [])
+    total, ok_count, hard_total, empty = 0, 0, 0, 0
+    for seq in seqs:
+        emails = seq.get("emails", [])
+        if not emails:
+            empty += 1
+            continue
+        total += 1
+        res = audit_sequence(emails, forbidden, expected_steps=expected)
+        if res["ok"]:
+            ok_count += 1
+        label = seq.get("_lead", {}).get("name") or seq.get("lead_id", "")[:8]
+        for issue in res["issues"]:
+            hard_total += 1
+            print(f"  ✗ {label}: {issue}")
+        for r in res["per_email"]:
+            for h in r["hard"]:
+                hard_total += 1
+                print(f"  ✗ {label} step {r['step']} ({r['word_count']}w): {h}")
+            for s in r["soft"]:
+                print(f"  · {label} step {r['step']}: {s}")
+    print(f"\n{ok_count}/{total} sequences clean | {empty} unfilled | {hard_total} hard issue(s)")
+    if empty:
+        print(f"  {empty} lead(s) have no emails yet — fill them before pushing.")
+    return 1 if (hard_total > 0 or empty > 0 or total == 0) else 0
+
+
+def cmd_push(args):
+    ready = _load(_ready_path(args, args.campaign_id))
+    items = []
+    for seq in ready.get("sequences", []):
+        emails = seq.get("emails", [])
+        if not emails or not seq.get("lead_id"):
+            continue
+        items.append({"lead_id": seq["lead_id"], "brief": seq.get("brief") or {}, "emails": emails})
+    if not items:
+        print("✗ nothing to push — no filled sequences in ready.json")
+        return 2
+
+    # Hard safety: re-run the gauntlet; never push hard-failing content.
+    forbidden = ready.get("forbidden_names", "")
+    bad = 0
+    for it in items:
+        res = audit_sequence(it["emails"], forbidden, expected_steps=ready.get("max_touches"))
+        if not res["ok"]:
+            bad += 1
+    if bad and not args.force:
+        print(f"✗ {bad} sequence(s) fail the gauntlet. Run `letz check` and fix, or use --force.")
+        return 1
+
+    # Push in batches so a large campaign never trips the request timeout.
+    # The endpoint is idempotent + atomic per request, so a failed batch can be
+    # safely retried by re-running push.
+    api = LetzAPI(args.api)
+    batch = max(1, args.batch)
+    total_imported = total_skipped = 0
+    last_status = None
+    for ci in range(0, len(items), batch):
+        chunk = items[ci:ci + batch]
+        res = api.import_sequences(args.campaign_id, chunk, stage=args.stage)
+        total_imported += res.get("imported", 0)
+        total_skipped += res.get("skipped", 0)
+        last_status = res.get("campaign_status")
+        done = min(ci + batch, len(items))
+        print(f"  · {done}/{len(items)} pushed (imported {res.get('imported')}, skipped {res.get('skipped')})")
+        for s in res.get("skipped_detail", []):
+            print(f"      skipped {s.get('lead_id','')[:8]}: {s.get('reason')}")
+    print(f"✓ imported {total_imported} | skipped {total_skipped} | campaign now: {last_status}")
+    if args.activate:
+        print("⚠️  --activate: flipping campaign to ACTIVE — the platform will begin sending in-window.")
+        a = api.activate(args.campaign_id)
+        print(f"✓ activated: {a.get('status', a)}")
+    else:
+        print(f"  Staged paused. Review in the UI, then `letz push {args.campaign_id} --activate` or click Activate.")
+    return 0
+
+
+def cmd_status(args):
+    api = LetzAPI(args.api)
+    camp = api.campaign(args.campaign_id) or {}
+    enrs = api.enrollments(args.campaign_id)
+    prev = api.previews(args.campaign_id)
+    sends = api.sends(args.campaign_id)
+    active = sum(1 for e in enrs if e.get("status") == "active")
+    sent = sum(1 for s in sends if s.get("status") == "sent")
+    print(f"Campaign : {camp.get('name','?')}  [{camp.get('status','?')}]")
+    print(f"Enrollments staged : {len(enrs)} ({active} active)")
+    print(f"Previews (review)  : {prev.get('total', 0)} ready")
+    print(f"Sends recorded     : {len(sends)} ({sent} sent)")
+    return 0
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="letz", description="Letz Brain CLI — off-platform generation, persist, click send.")
+    p.add_argument("--api", default=os.environ.get("LETZ_API_URL", "http://localhost:8000"), help="platform base URL")
+    p.add_argument("--work", default=None, help="work dir (default ./letz_work)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("pull", help="fetch campaign + leads, write a ready.json scaffold")
+    sp.add_argument("campaign_id")
+    sp.add_argument("--limit", type=int, default=1000)
+    sp.add_argument("--force", action="store_true", help="overwrite an existing ready.json scaffold")
+    sp.set_defaults(func=cmd_pull)
+
+    sp = sub.add_parser("check", help="run the pure-Python quality gauntlet on ready.json")
+    sp.add_argument("campaign_id")
+    sp.set_defaults(func=cmd_check)
+
+    sp = sub.add_parser("push", help="import staged sequences (paused) via POST /sequences/import")
+    sp.add_argument("campaign_id")
+    sp.add_argument("--stage", choices=["paused", "leave"], default="paused")
+    sp.add_argument("--batch", type=int, default=25, help="leads per import request (avoids timeouts on big campaigns)")
+    sp.add_argument("--activate", action="store_true", help="flip campaign to active after import (SENDS)")
+    sp.add_argument("--force", action="store_true", help="push even if the gauntlet fails")
+    sp.set_defaults(func=cmd_push)
+
+    sp = sub.add_parser("status", help="show staged enrollments / previews / sends")
+    sp.add_argument("campaign_id")
+    sp.set_defaults(func=cmd_status)
+
+    args = p.parse_args(argv)
+    try:
+        return args.func(args)
+    except FileNotFoundError as e:
+        print(f"✗ {e}. Run `letz pull {getattr(args,'campaign_id','<id>')}` first.")
+        return 2
+    except LetzAPIError as e:
+        print(f"✗ API error {e.status}: {e.body}")
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

letz_cli-0.1.0/letz/api.py

@@ -0,0 +1,79 @@
+"""Thin HTTP client for the Letz platform API (stdlib only).
+
+A pure reader/writer over HTTP: it talks to the platform's public REST API
+and nothing else, so pushing drafts can never trigger a send by itself.
+"""
+from __future__ import annotations
+import json
+import urllib.request
+import urllib.error
+
+
+class LetzAPIError(Exception):
+    def __init__(self, status, body):
+        self.status = status
+        self.body = body
+        super().__init__(f"HTTP {status}: {str(body)[:300]}")
+
+
+class LetzAPI:
+    def __init__(self, base_url: str = "http://localhost:8000", timeout: int = 120):
+        self.base = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _req(self, method: str, path: str, body=None):
+        url = self.base + ("/api/v1" if not path.startswith("/api/") else "") + path
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(
+            url, data=data, method=method,
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode() or "{}"
+                return json.loads(raw)
+        except urllib.error.HTTPError as e:
+            try:
+                payload = json.loads(e.read().decode() or "{}")
+            except Exception:
+                payload = {"detail": "unreadable error body"}
+            raise LetzAPIError(e.code, payload)
+
+    # ---- reads ----
+    def campaign(self, campaign_id: str) -> dict | None:
+        """No single-campaign GET exists; fetch the list and filter."""
+        data = self._req("GET", "/campaigns?limit=200")
+        for c in data.get("campaigns", []):
+            if c.get("id") == campaign_id:
+                return c
+        return None
+
+    def leads(self, campaign_id: str, limit: int = 1000) -> list:
+        data = self._req("GET", f"/campaigns/{campaign_id}/leads?limit={limit}")
+        return data.get("leads", [])
+
+    def persona(self) -> dict:
+        try:
+            return self._req("GET", "/brand-persona")
+        except LetzAPIError:
+            return {}
+
+    def previews(self, campaign_id: str) -> dict:
+        return self._req("GET", f"/campaigns/{campaign_id}/previews")
+
+    def enrollments(self, campaign_id: str) -> list:
+        return self._req("GET", f"/sequences/enrollments?campaign_id={campaign_id}").get("enrollments", [])
+
+    def sends(self, campaign_id: str, limit: int = 200) -> list:
+        return self._req("GET", f"/sequences/sends?campaign_id={campaign_id}&limit={limit}").get("sends", [])
+
+    # ---- writes ----
+    def import_sequences(self, campaign_id: str, items: list, stage: str = "paused") -> dict:
+        return self._req("POST", "/sequences/import",
+                         {"campaign_id": campaign_id, "items": items, "stage": stage})
+
+    def activate(self, campaign_id: str) -> dict:
+        return self._req("POST", f"/campaigns/{campaign_id}/activate")
+
+    def pause(self, campaign_id: str) -> dict:
+        return self._req("POST", f"/campaigns/{campaign_id}/pause")

letz_cli-0.1.0/letz/gauntlet.py

@@ -0,0 +1,124 @@
+"""Pure-Python quality gauntlet for the Letz Brain CLI.
+
+Parity port of the platform's DETERMINISTIC email checks so off-platform
+generation meets the same bar the in-app critic enforced — with ZERO AI.
+
+Sources mirrored:
+  - services/critic.py:_deterministic_penalties + BAD_PHRASES
+  - services/email_audit.py:audit_email_deterministic + BANNED_PHRASES
+Plus the operator's hard rule: NO em dashes.
+
+The LLM-rubric half of the critic is replaced by careful generation upstream;
+this module is the hard gate that runs locally before anything is pushed.
+"""
+from __future__ import annotations
+import re
+
+EM_DASH = "—"   # —
+EN_DASH = "–"   # –
+
+# Union of services/critic.py BAD_PHRASES and services/email_audit.py BANNED_PHRASES.
+BANNED_PHRASES = sorted(set([
+    "i hope this email finds you well", "i hope this finds you well",
+    "i hope you're well", "hope you're doing well", "i wanted to reach out",
+    "just reaching out", "i came across your", "circle back", "circling back",
+    "touch base", "synergy", "leverage our", "leverage", "deep dive",
+    "going forward", "low-hanging fruit", "move the needle",
+    "at your earliest convenience", "let me know your thoughts", "quick question",
+    "following up", "just following up", "checking in", "as per my last email",
+    "as discussed", "boil the ocean", "drink from the fire hose",
+]))
+
+# Brevity: ideal ceiling and a hard ceiling (mirrors email_audit 90 * 1.45 ~ 130;
+# critic used 150/180). We keep a generous hard ceiling so short, human notes pass.
+IDEAL_MAX_WORDS = 120
+HARD_MAX_WORDS = 180
+MIN_WORDS = 25
+
+
+def audit_email(subject: str, body: str, forbidden_names=None) -> dict:
+    """Audit one email. Returns {ok, hard, soft, word_count}.
+
+    `hard` issues MUST be fixed before pushing (the CLI `check` fails on any).
+    `soft` issues are advisory.
+    """
+    subject = (subject or "").strip()
+    body = (body or "").strip()
+
+    if isinstance(forbidden_names, str):
+        forbidden = [n.strip() for n in forbidden_names.split(",") if n.strip()]
+    elif isinstance(forbidden_names, (list, tuple)):
+        forbidden = [str(n).strip() for n in forbidden_names if str(n).strip()]
+    else:
+        forbidden = []
+
+    hard: list[str] = []
+    soft: list[str] = []
+
+    # --- empties ---
+    if not subject:
+        hard.append("Subject is empty.")
+    elif len(subject) < 6:
+        hard.append(f"Subject is too short ({len(subject)} chars) — make it specific.")
+    elif len(subject) > 70:
+        soft.append("Subject is over 70 chars — cap ~60 so it renders on mobile.")
+    if not body:
+        hard.append("Body is empty.")
+
+    combined = f"{subject}\n{body}"
+    combined_lc = combined.lower()
+
+    # --- NO em dashes (operator rule) ---
+    if EM_DASH in combined or EN_DASH in combined:
+        hard.append("Contains an em/en dash — replace with a comma, period, or rewrite.")
+
+    # --- banned / templated phrases ---
+    hits = [p for p in BANNED_PHRASES if p in combined_lc]
+    if hits:
+        hard.append(f"Templated/spam phrase(s): {', '.join(hits[:4])}.")
+
+    # --- forbidden names (operator real name etc.) ---
+    leaks = [n for n in forbidden if re.search(rf"\b{re.escape(n)}\b", combined, re.IGNORECASE)]
+    if leaks:
+        hard.append(f"Forbidden name(s) leaked: {', '.join(leaks)}.")
+
+    # --- brevity ---
+    word_count = len(body.split())
+    if word_count > HARD_MAX_WORDS:
+        hard.append(f"Body is {word_count} words — over the {HARD_MAX_WORDS} hard ceiling. Cut it.")
+    elif word_count > IDEAL_MAX_WORDS:
+        soft.append(f"Body is {word_count} words — over the {IDEAL_MAX_WORDS} ideal. Trim.")
+    if 0 < word_count < MIN_WORDS:
+        soft.append(f"Body is only {word_count} words — add one specific, concrete detail.")
+
+    # --- link density ---
+    links = len(re.findall(r"https?://", body))
+    if links > 2:
+        hard.append(f"{links} links — one max, ideally just the CTA.")
+    elif links == 2:
+        soft.append("Two links — prefer one.")
+
+    # --- one clear ask ---
+    q = body.count("?")
+    if q == 0:
+        soft.append("No question/ask — end with one soft yes/no question.")
+    elif q >= 3:
+        soft.append(f"{q} questions — pick the single best ask.")
+
+    return {"ok": len(hard) == 0, "hard": hard, "soft": soft, "word_count": word_count}
+
+
+def audit_sequence(emails: list, forbidden_names=None, expected_steps: int | None = None) -> dict:
+    """Audit a full sequence. Returns {ok, per_email:[...], issues:[...]}."""
+    issues: list[str] = []
+    per_email = []
+    if not emails:
+        return {"ok": False, "per_email": [], "issues": ["No emails in sequence."]}
+    if expected_steps and len(emails) < expected_steps:
+        issues.append(f"Only {len(emails)} of {expected_steps} expected touches.")
+    for i, e in enumerate(emails):
+        r = audit_email(e.get("subject", ""), e.get("body", ""), forbidden_names)
+        r["step"] = e.get("step", i + 1)
+        per_email.append(r)
+    ok = all(r["ok"] for r in per_email) and not issues
+    return {"ok": ok, "per_email": per_email, "issues": issues}

letz_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "letz-cli"
+dynamic = ["version"]
+description = "Letz Brain CLI - pull campaigns from the Letz platform, draft email sequences locally with Claude, and push them back staged for review."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Letz" }]
+keywords = ["letz", "sdr", "outreach", "email", "sequences", "claude"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Other Audience",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+]
+
+[project.scripts]
+letz = "letz.__main__:main"
+
+[project.urls]
+Homepage = "https://sam.weareletz.com"
+
+[tool.hatch.version]
+path = "letz/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+ignore-vcs = true
+only-include = ["letz", "README.md", "LICENSE", "pyproject.toml"]
+exclude = ["**/__pycache__"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["letz"]