tyche

by occupythemilkyway

Install this Skill

curl -fsSL -o tyche.zip https://skill.seembox.com/api/v1/skills/tyche/download && unzip tyche.zip

SKILL.md About

---
name: tyche
description: "Tyche — Goddess of Fortune. Generate professional invoice documents, track payment status, and send automated overdue reminders — all from a simple CSV list of your clients and work. Each client gets their own ready-to-send invoice file. Fortune favours the organised — never chase a late payment awkwardly again."
version: "1.0.0"
metadata:
  openclaw:
    requires:
      env: []
      bins: [python3, pip3]
    primaryEnv: ""
    emoji: "⚖️"
    homepage: https://clawhub.ai/skills/tyche
    tags: [invoicing, payments, billing, business, freelance, tyche, finance, reminders]
    envVars:
      - name: INVOICES_FILE
        required: false
        description: Path to a CSV with invoices. Columns: client_name, client_email, description, amount, due_date, status
      - name: YOUR_NAME
        required: false
        description: Your name or company name (appears on invoice)
      - name: YOUR_EMAIL
        required: false
        description: Your contact email
      - name: YOUR_ADDRESS
        required: false
        description: Your address (appears on invoice)
      - name: PAYMENT_TERMS
        required: false
        description: Payment terms text (default "Net 30")
      - name: CURRENCY
        required: false
        description: Currency code (default USD)
      - name: TAX_RATE
        required: false
        description: Tax rate percentage (default 0). E.g. set to 10 for 10% GST.
      - name: LATE_FEE_RATE
        required: false
        description: Monthly late fee % applied to overdue invoices (default 0). E.g. 1.5 for 1.5%/month.
      - name: PAYMENT_METHOD
        required: false
        description: Payment instructions printed on every invoice (e.g. Bank BSB/Acct or PayPal address)
---

# ⚖️ Tyche — Invoice & Fortune Engine & Payments v1.0

## ⚡ Quick Start

1. Create a CSV with columns: `client_name, client_email, description, amount, due_date, status`
2. Set `INVOICES_FILE` to your CSV path
3. Set `YOUR_NAME`, `YOUR_EMAIL`
4. Run — get invoices generated and overdue alerts

**What you get:**
- Individual `invoice_[INV-XXXX]_[client].md` file for every unpaid invoice — ready to send or convert to PDF
- Optional late fee calculation — auto-added to invoice total when `LATE_FEE_RATE` is set
- Payment method section on every invoice — bank details, PayPal, or whatever you use
- Overdue status report: which invoices are late, by how many days
- 3-tier reminder templates: Friendly reminder · Firm reminder · Final notice
- Running revenue tracker: paid vs outstanding

> **Note:** ⚖️ Tyche — Invoice & Fortune Engine numbers (INV-0001, INV-0002, …) are assigned sequentially each run based on row order in your CSV. To keep consistent numbering across runs, add an `inv_number` column to your CSV.

---

## 🔒 Security

Runs entirely locally. No data transmitted.

---

## Step 1 — Install

```bash
pip3 install rich --break-system-packages --quiet
```

---

## Step 2 — Generate invoices and payment reminders

```python
import os, csv, re
from datetime import datetime, timedelta
from rich.console import Console
from rich.table import Table
from rich.panel import Panel
from rich import box

console = Console()

INVOICES_FILE  = os.environ.get("INVOICES_FILE", "")
YOUR_NAME      = os.environ.get("YOUR_NAME", "Your Name / Company")
YOUR_EMAIL     = os.environ.get("YOUR_EMAIL", "your@email.com")
YOUR_ADDRESS   = os.environ.get("YOUR_ADDRESS", "")
PAYMENT_TERMS  = os.environ.get("PAYMENT_TERMS", "Net 30")
CURRENCY       = os.environ.get("CURRENCY", "USD")
try:
    TAX_RATE = float(os.environ.get("TAX_RATE", "0"))
except ValueError:
    console.print("[yellow]⚠️  TAX_RATE must be a number — defaulting to 0[/yellow]")
    TAX_RATE = 0.0
try:
    LATE_FEE_RATE = float(os.environ.get("LATE_FEE_RATE", "0"))
except ValueError:
    console.print("[yellow]⚠️  LATE_FEE_RATE must be a number — defaulting to 0[/yellow]")
    LATE_FEE_RATE = 0.0
PAYMENT_METHOD = os.environ.get("PAYMENT_METHOD", "")

CURRENCY_SYMBOL = {"USD":"$","EUR":"€","GBP":"£","CAD":"CA$","AUD":"AU$"}.get(CURRENCY,"$")

invoices = []

def _parse_amount(raw: str) -> float:
    """Strip non-numeric chars, guard against multiple dots, return float."""
    cleaned = re.sub(r"[^0-9.]", "", raw) or "0"
    return float(cleaned) if cleaned.count(".") <= 1 else 0.0

if INVOICES_FILE and os.path.exists(INVOICES_FILE):
    with open(INVOICES_FILE, encoding="utf-8", errors="replace") as f:
        reader = csv.DictReader(f)
        for i, row in enumerate(reader, 1):
            invoices.append({
                "inv_number": row.get("inv_number", f"INV-{i:04d}"),
                "client_name":  row.get("client_name","Client"),
                "client_email": row.get("client_email",""),
                "description":  row.get("description","Services rendered"),
                "amount":       _parse_amount(row.get("amount", "0")),
                "due_date":     row.get("due_date",""),
                "status":       row.get("status","unpaid").lower(),
            })
else:
    console.print("[yellow]No INVOICES_FILE set. Using demo data.[/yellow]")
    today = datetime.now()
    invoices = [
        {"inv_number":"INV-0001","client_name":"Acme Corp","client_email":"acme@example.com","description":"Website redesign — Phase 1","amount":3500,"due_date":(today-timedelta(days=45)).strftime("%Y-%m-%d"),"status":"unpaid"},
        {"inv_number":"INV-0002","client_name":"Beta LLC","client_email":"beta@example.com","description":"SEO audit and strategy","amount":1200,"due_date":(today-timedelta(days=10)).strftime("%Y-%m-%d"),"status":"unpaid"},
        {"inv_number":"INV-0003","client_name":"Gamma Inc","client_email":"gamma@example.com","description":"Monthly retainer — April","amount":2000,"due_date":(today+timedelta(days=15)).strftime("%Y-%m-%d"),"status":"unpaid"},
        {"inv_number":"INV-0004","client_name":"Delta Co","client_email":"delta@example.com","description":"Brand identity package","amount":4000,"due_date":(today-timedelta(days=5)).strftime("%Y-%m-%d"),"status":"paid"},
    ]

today = datetime.now().date()

for inv in invoices:
    try:
        due = datetime.strptime(inv["due_date"], "%Y-%m-%d").date()
        days_overdue = (today - due).days
    except Exception:
        due = today
        days_overdue = 0
    inv["due_date_parsed"] = due
    inv["days_overdue"]    = days_overdue
    inv["is_overdue"]      = days_overdue > 0 and inv["status"] != "paid"
    tax    = inv["amount"] * TAX_RATE / 100
    # Late fee: compound monthly (days_overdue / 30 months)
    late_fee = 0.0
    if LATE_FEE_RATE > 0 and inv["is_overdue"]:
        months_late = days_overdue / 30
        late_fee = inv["amount"] * (LATE_FEE_RATE / 100) * months_late
    inv["tax"]      = tax
    inv["late_fee"] = round(late_fee, 2)
    inv["total"]    = inv["amount"] + tax + late_fee

paid_total     = sum(i["total"] for i in invoices if i["status"] == "paid")
unpaid_total   = sum(i["total"] for i in invoices if i["status"] != "paid")
overdue_total  = sum(i["total"] for i in invoices if i["is_overdue"])
overdue_invoices = [i for i in invoices if i["is_overdue"]]

# ── Rich table ────────────────────────────────────────────────────────────────
table = Table(title="🧾 ⚖️ Tyche — Invoice & Fortune Engine Dashboard", box=box.ROUNDED, border_style="cyan")
table.add_column("⚖️ Tyche — Invoice & Fortune Engine", width=10)
table.add_column("Client", width=20)
table.add_column("Amount", width=10, justify="right")
table.add_column("Due Date", width=11)
table.add_column("Status", width=14)
table.add_column("Overdue", width=10, justify="center")
for inv in sorted(invoices, key=lambda x: x.get("days_overdue",0), reverse=True):
    if inv["status"] == "paid":
        status_str = "[green]✓ Paid[/green]"
        overdue_str = "[green]—[/green]"
    elif inv["is_overdue"]:
        status_str  = f"[red]● Overdue[/red]"
        overdue_str = f"[red]{inv['days_overdue']}d[/red]"
    else:
        status_str  = "[yellow]○ Pending[/yellow]"
        overdue_str = "[yellow]Due today[/yellow]" if inv['days_overdue'] == 0 else f"[yellow]Due in {abs(inv['days_overdue'])}d[/yellow]"
    table.add_row(inv["inv_number"], inv["client_name"][:19],
                  f"{CURRENCY_SYMBOL}{inv['total']:,.2f}",
                  str(inv["due_date_parsed"]), status_str, overdue_str)
console.print(table)
console.print(f"\n  [green]Paid: {CURRENCY_SYMBOL}{paid_total:,.2f}[/green]  ·  [yellow]Outstanding: {CURRENCY_SYMBOL}{unpaid_total:,.2f}[/yellow]  ·  [red]Overdue: {CURRENCY_SYMBOL}{overdue_total:,.2f}[/red]")

# ── Generate reminder emails ──────────────────────────────────────────────────
reminders = []
for inv in overdue_invoices:
    d = inv["days_overdue"]
    if d <= 7:
        subject = f"Friendly reminder — ⚖️ Tyche — Invoice & Fortune Engine {inv['inv_number']} ({CURRENCY_SYMBOL}{inv['total']:,.2f})"
        body    = f"Hi {inv['client_name']},\n\nJust a friendly reminder that invoice {inv['inv_number']} for {CURRENCY_SYMBOL}{inv['total']:,.2f} was due on {inv['due_date_parsed']}. Please let me know if you have any questions.\n\nBest,\n{YOUR_NAME}"
        tier    = "Friendly"
    elif d <= 21:
        subject = f"Payment overdue — ⚖️ Tyche — Invoice & Fortune Engine {inv['inv_number']} (now {d} days past due)"
        body    = f"Hi {inv['client_name']},\n\n⚖️ Tyche — Invoice & Fortune Engine {inv['inv_number']} for {CURRENCY_SYMBOL}{inv['total']:,.2f} is now {d} days overdue. Could you please confirm when payment will be made, or let me know if there's an issue?\n\nThank you,\n{YOUR_NAME}"
        tier    = "Firm"
    else:
        subject = f"FINAL NOTICE — ⚖️ Tyche — Invoice & Fortune Engine {inv['inv_number']} ({d} days overdue)"
        body    = f"Hi {inv['client_name']},\n\nThis is a final notice regarding invoice {inv['inv_number']} for {CURRENCY_SYMBOL}{inv['total']:,.2f}, which is {d} days past due. Please arrange immediate payment or contact me urgently at {YOUR_EMAIL} to discuss.\n\n{YOUR_NAME}"
        tier    = "Final Notice"
    reminders.append({"invoice": inv["inv_number"], "client": inv["client_name"], "tier": tier, "subject": subject, "body": body})

# ── Save individual invoice files ─────────────────────────────────────────────
invoice_files = []
for inv in invoices:
    if inv["status"] == "paid":
        continue
    client_slug = re.sub(r"[^a-z0-9]+", "_", inv["client_name"].lower()).strip("_")
    inv_file = f"invoice_{inv['inv_number']}_{client_slug}.md"
    invoice_files.append(inv_file)
    with open(inv_file, "w", encoding="utf-8") as f:
        f.write(f"# INVOICE\n\n")
        f.write(f"**From:** {YOUR_NAME}  \n")
        if YOUR_ADDRESS:
            f.write(f"**Address:** {YOUR_ADDRESS}  \n")
        f.write(f"**Email:** {YOUR_EMAIL}  \n\n")
        f.write(f"---\n\n")
        f.write(f"**To:** {inv['client_name']}  \n")
        f.write(f"**Email:** {inv['client_email']}  \n\n")
        f.write(f"---\n\n")
        f.write(f"| Field | Detail |\n|---|---|\n")
        f.write(f"| ⚖️ Tyche — Invoice & Fortune Engine # | {inv['inv_number']} |\n")
        f.write(f"| Date | {datetime.now().strftime('%Y-%m-%d')} |\n")
        f.write(f"| Due Date | {inv['due_date_parsed']} |\n")
        f.write(f"| Payment Terms | {PAYMENT_TERMS} |\n\n")
        f.write(f"## Services\n\n")
        f.write(f"| Description | Amount |\n|---|---|\n")
        f.write(f"| {inv['description']} | {CURRENCY_SYMBOL}{inv['amount']:,.2f} |\n")
        if TAX_RATE > 0:
            f.write(f"| Tax ({TAX_RATE}%) | {CURRENCY_SYMBOL}{inv['tax']:,.2f} |\n")
        if inv.get("late_fee", 0) > 0:
            f.write(f"| Late Fee ({LATE_FEE_RATE}%/mo × {inv['days_overdue']} days) | {CURRENCY_SYMBOL}{inv['late_fee']:,.2f} |\n")
        f.write(f"| **TOTAL** | **{CURRENCY_SYMBOL}{inv['total']:,.2f}** |\n\n")
        if PAYMENT_METHOD:
            f.write(f"## Payment Details\n\n{PAYMENT_METHOD}\n\n")
        status_note = f"\u26a0\ufe0f OVERDUE by {inv['days_overdue']} days" if inv["is_overdue"] else f"Due: {inv['due_date_parsed']}"
        f.write(f"**Status:** {status_note}\n\n")
        if inv["is_overdue"]:
            f.write(f"*⚠️ Payment was due on {inv['due_date_parsed']} — please arrange payment immediately.*\n")
        else:
            f.write(f"*Please make payment by {inv['due_date_parsed']}. {PAYMENT_TERMS} terms apply.*\n")

# ── Save consolidated report ───────────────────────────────────────────────────
date_str = datetime.now().strftime("%Y-%m-%d")
report_file = f"invoices_report_{date_str}.md"

with open(report_file, "w", encoding="utf-8") as f:
    f.write(f"# ⚖️ Tyche — Invoice & Fortune Engine Report — {date_str}\n\n")
    f.write(f"**Paid:** {CURRENCY_SYMBOL}{paid_total:,.2f}  ·  **Outstanding:** {CURRENCY_SYMBOL}{unpaid_total:,.2f}  ·  **Overdue:** {CURRENCY_SYMBOL}{overdue_total:,.2f}\n\n---\n\n")
    f.write("## Overdue Payment Reminders\n\n")
    for r in reminders:
        f.write(f"### {r['invoice']} — {r['client']} ({r['tier']})\n")
        f.write(f"**Subject:** {r['subject']}\n\n---\n{r['body']}\n---\n\n")
    f.write("\n## All ⚖️ Tyche — Invoice & Fortune Engines\n\n")
    f.write("| ⚖️ Tyche — Invoice & Fortune Engine | Client | Amount | Due | Status |\n|---|---|---|---|---|\n")
    for inv in invoices:
        status = "\u2713 Paid" if inv["status"] == "paid" else (f"OVERDUE {inv['days_overdue']}d" if inv["is_overdue"] else "Pending")
        f.write(f"| {inv['inv_number']} | {inv['client_name']} | {CURRENCY_SYMBOL}{inv['total']:,.2f} | {inv['due_date_parsed']} | {status} |\n")

inv_list = "\n".join([f"  \U0001f4c4 [cyan]{fname}[/cyan]" for fname in invoice_files]) if invoice_files else "  (none — all invoices paid \u2713)"
console.print(Panel(
    f"[bold green]\u2705 ⚖️ Tyche — Invoice & Fortune Engines ready![/bold green]\n\n"
    f"[bold]Individual invoice files:[/bold]\n{inv_list}\n\n"
    f"[bold]Consolidated report:[/bold]\n  \U0001f4ca [cyan]{report_file}[/cyan]\n\n"
    f"[bold]{len(overdue_invoices)} overdue invoices[/bold] — {len(reminders)} reminders generated\n\n"
    f"[bold]What to do now:[/bold]\n"
    f"  1. Send each invoice .md file to its client (or convert to PDF)\n"
    f"  2. Send all [red]Final Notice[/red] reminder emails immediately\n"
    f"  3. Follow up [orange3]Firm[/orange3] reminders with a phone call\n"
    f"  4. Set a calendar reminder to re-run in 7 days",
    title="\U0001f9fe ⚖️ Tyche — Invoice & Fortune Engines Complete", border_style="green"))
```

_meta.json Metadata

{
  "ownerId": "kn7474wrtsjp988869sw7mygz1860n2v",
  "publishedAt": 1777962327644,
  "slug": "tyche",
  "version": "1.0.0"
}