Self-hosted invoicing agent with payment reminders

An autonomous billing agent you deploy on a Debian VM in one command. It runs a reliable deterministic core out of the box, and gets smart when you connect your existing coding-agent subscription - Claude Code, Kimi Code, or Codex - with no API key.

Architecture

-----------------------------------------------------------------------------
|                        AGENT BILLING v1.0                                  |
|----------------------------------------------------------------------------|
|  +-------------+   +-------------+   +-------------+   +----------+       |
|  |  Producer   |-->|   Queue     |-->| Dispatcher  |-->| Executor |       |
|  | (cron/CLI)  |   |  (SQLite)   |   | (OODA loop) |   | (LLM/.)  |       |
|  +-------------+   +------+------+   +-------------+   +-----+----+       |
|                           |                                  |             |
|                    +------+------+                    +------+-----+       |
|                    | Dead Letter |<-------------------|   Retry    |       |
|                    |   Queue     |   (max 3 attempts) |  Policy    |       |
|                    +------+------+                    +----------+       |
|                           ^                                              |
|                           |                                              |
|  +---------------------------------------------------------------------+  |
|  |                         Monitor                                      |  |
|  |  (queue depth / dead-letter / overdue invoices / backpressure)      |  |
|  +---------------------------------------------------------------------+  |
-----------------------------------------------------------------------------

• Producer : cron, CLI (agent.py enqueue), ou API externe
• Queue : SQLite locale par defaut, zero-config, zero-deps
• Dispatcher : boucle OODA - observe, oriente, decide, agit
• Executor : mode deterministe (.) par defaut, mode LLM si CLI connectee
• Retry Policy : backoff exponentiel 10s -> 60s -> 600s
• Dead Letter : taches en echec conservees, replayables
• Monitor : sondes integrees, alertes configurables

One-shot install (Debian/Ubuntu)

unzip agent-billing-v1.zip && cd agent-billing-v1
sudo bash install.sh          # system deps + venv + systemd service (enabled)

That's it. The agent starts as a systemd service (agent-billing-v1), survives reboots, and restarts on failure. Logs: journalctl -u agent-billing-v1 -f.

No root / no systemd? bash install.sh --no-service sets up the venv, then run venv/bin/python agent.py run.

Connect your LLM (optional, no API key)

install.sh auto-detects the first CLI it finds. Install & log in to one:

Force a specific one with PACK_LLM=claude|kimi|codex. If none is connected, the agent still runs - see the honesty table below.

What's LLM vs deterministic (honest by design)

If a CLI is installed but not logged in, the agent logs a warning and falls back to the deterministic handler for that task - it never gets stuck.

Business-state integrity (no hallucinated invoices)

The LLM reasons, but business ids come from the system, never from the model. A real invoice_id may only come from (a) your input data, (b) a deterministic generator, or (c) the billing system's response after a real creation. The agent enforces this on every LLM output before a task can complete (validate_no_fabricated_invoice_ids in agent.py):

• An invoice you plan to create is emitted with invoice_id: null ("to_be_generated") — never an invented INV-2026-0004.
• A payment without a real invoice_id is never invoice_marked_paid; it is parked as awaiting_invoice_creation / candidate_match_pending_creation / manual_review / ignored_duplicate.
• Reconciling a payment to an invoice is a separate step that runs only after the invoice has really been created and its id returned.
• Any output that invents an id, or marks paid a non-existing invoice, is rejected: the task fails and goes to the dead-letter / human-review channel. Nothing fabricated is ever silently accepted.

Exact output list shapes (enforced by the validator):

• payments_to_reconcile_after_creation: each item is a verbatim copy of the input payment object with ONLY the keys payment_id, customer, amount, currency, status. Adding match_target, reconcile_after_invoice_creation or any other key not present in the source is forbidden.
• invoices_to_create: verbatim projection of the source fields only. Adding payment_id or status:"to_be_generated" is forbidden.
• No extra key beyond the input source is ever added to any output list.

Correct cycle: plan invoice → create it via the deterministic system/API → get the real invoice_id back → reconcile the payment → log the result.

The reconcile_billing task does this deterministically (no LLM needed):

python agent.py enqueue --type reconcile_billing --payload '{
  "existing_invoices":[{"invoice_id":"INV-2026-0003","customer":"Acme","amount":1200}],
  "invoices_to_create":[{"customer":"Globex","amount":900}],
  "payments":[{"customer":"Globex","amount":900,"status":"settled"}]
}'

Quick commands

python agent.py status
python agent.py enqueue --type generate_invoice --payload '{"customer":"Acme","amount":1200,"due_date":"2026-06-30"}'
python agent.py enqueue --type send_reminder --payload '{"customer":"Acme","invoice_id":"INV-001"}'
python agent.py enqueue --type record_payment --payload '{"customer":"Acme","invoice_id":"INV-001","amount_paid":1200}'
python agent.py enqueue --type cleanup --idempotency-key nightly-2026-06-07
python agent.py run --once                   # one OODA cycle
python agent.py run --deterministic          # force the no-LLM core
python agent.py replay --task t-ab12cd34     # requeue a dead/blocked task
bash smoke_test.sh                           # offline test suite (no keys)
python EXAMPLE.py                            # runnable end-to-end demo

Contents

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.