margin-check

A spell-checker for profit: it catches giveaways in your sales emails and turns them into fair PayPal draft invoices before you hit send.

Comment

Inspiration

Small businesses negotiate wholesale lots, custom orders, and service packages over email every single day. In the rush to close a deal or keep a buyer happy, sellers routinely agree to requests like "Can you do free shipping and net 60 days?" without calculating the compounding impact.

Friendly agreements silently leak profit across multiple channels: uncalculated volume discounts, absorbed shipping freight, the carrying cost of waiting two months for payment, and merchant processing fees. A deal that looks like a great sale on the surface can easily turn into an unprofitable loss once the real costs land.

Sellers don't need another generic dashboard or an autonomous bot that fires off emails behind their back. They need a spell-checker for profit: a vigilant assistant that reads incoming negotiation emails, flags margin leaks with whole-cent arithmetic, drafts principled counter-offers, and prepares approved draft invoices in PayPal—keeping the seller firmly in control of every dollar and every communication.

What it does

margin-check is a local web application (http://127.0.0.1:8787) that guides sellers through five interactive stations, and ships with a one-command safety proof:

Understand (Dual-Model Reading): When an email thread is pasted, two independent Google Gemini models (gemini-3.5-flash-lite and gemini-3.1-flash-lite) extract structured deal terms (quantities, prices, shipping terms, and payment schedules). An extraction is marked "sure" only if both models reach consensus, every single figure matches an exact sentence quote in the thread, and all values pass schema validation. If anything is ambiguous or unstated, the system asks the seller instead of guessing. Check (Whole-Cent Profit Engine): A deterministic Go engine evaluates the agreed terms against the seller's cost parameters across eight recognized margin leaks (order-size discounts, general discounts, volume rebates, freight, payment term carrying costs, cash discounts, marketing allowances, and PayPal fees). It displays the kept profit and highlights giveaways (for example, marking "$49.15 given away" on a deal leaking margin). Why the buyer may be asking (a note for the seller only): a separate AI call offers at most two guesses at the interest behind the request (for example, cash flow before a busy season, or a small storeroom), following Getting to Yes: look behind each position and ask "Why?". Code keeps a guess only if it is said as a guess ("The buyer may…"), carries no figure, describes the buyer rather than advising the seller, and quotes words the buyer really wrote. "Can't tell" is an allowed answer. The note is never given to the reply writer, so it can't reach the buyer. Choices (Three Principled Counter-Offers): Rather than "splitting the difference" or conceding margin, the engine calculates three fair options rooted in objective economic criteria: Option 1 (Standard): List price with shipping at cost and payment due on receipt. Option 2 (Quantity): A higher order volume threshold where economies of scale cover the cost of shipping. Option 3 (Early Payment): A discount (e.g. 1.5% off) on an invoice due in 7 days, sized so the money saved by being paid sooner covers it. The discount is written on the draft itself (decision 0020, "plan B"), because the sandbox's own early-payment rule couldn't be automated; the seller sees that on screen, and the buyer keeps the discount even if they pay late. Write (Guarded AI Reply Drafting): Gemini drafts a warm, professional email response presenting the three choices with calibrated "how" or "what" questions. To ensure mathematical safety, Go validators reject any draft containing numbers, currency symbols, or percentages. Code deterministically injects all calculated prices and terms into structural blanks. Act (The Agentic Commerce Loop): When the buyer replies, even with a short "Option 2 please", the agent reads the answer against the choices it sent and identifies which option was accepted, quoting the buyer's own words (our own offer text never counts as the buyer agreeing). The page marks the AI's reading on a row of choice buttons, so the seller confirms or corrects it with one tap; a tap still stops if the buyer stated a different term, and nothing can be switched once a draft exists. It proposes an action plan consisting of two tools: creating a draft invoice via PayPal's official Agent Toolkit MCP server and setting payment due dates via PayPal's REST API. The action plan produces a cryptographic SHA-256 fingerprint binding tool names, parameters, and sequence. Execution runs only when the seller explicitly approves that exact fingerprint. Once created in the PayPal Sandbox, the client performs a field-by-field read-back to verify that the draft matches planned values. Automated Safety Proof: With a single command (go run ./cmd/proof), judges can verify the entire reading exam, profit mathematics, duplicate prevention, and twelve plan-tampering attacks in seconds, with no API keys, no AI calls and no cost.

How we built it

We treated this as an engineering problem first: an AI agent that prepares money actions is exactly where AI systems fail. Before building each part, we checked the design against the engineering literature: Designing Data-Intensive Applications, AI Engineering (Chip Huyen), Building Agentic AI Systems, the OWASP Agentic Top 10, Security Engineering, The Design of Everyday Things, and others. Then we checked the code against the design. docs/ENGINEERING.md maps each principle to the test or output that proves it (27 claims, each checked by script and read by hand). Highlights:

Evaluation before the system: the 20-email exam and its answer key were committed a day before the AI reader existed. A proof that can't be fooled: with the interceptor deliberately switched off in a scratch copy, proof reports 0 of 12 tampered plans blocked and fails. Seven layers between an email and PayPal, from exact-quote matching to PayPal read-back. An append-only decision log per deal. The approval is written before PayPal is called, and no run happens without its record. An Approve button that names the exact action, against the known failure where people approve automated recommendations without reading them. We built margin-check following the LLM-Modulo architecture: artificial intelligence proposes candidate extractions, drafted prose, and action plans, while deterministic Go code verifies every number, quote, and parameter before anything takes effect.

Single Go Architecture (Decision 0014): Implemented in Go 1.26 as a cohesive binary, cleanly isolating the profit math, web server, and PayPal integration layers into 17 tested packages. Three Bounded AI Responsibilities (Decision 0015): The AI performs exactly three scoped jobs: reading untrusted email text (with zero external tools), drafting conversational wording around blanks, and planning invoice calls (without ever seeing raw untrusted email text). Dual Gemini Models (Decisions 0016, 0018, 0019): Deployed gemini-3.5-flash-lite and gemini-3.1-flash-lite on the free tier to provide independent cross-model validation without incurring paid billing overhead. Deterministic Whole-Cent Arithmetic: Float data types are banned for financial calculations. All monetary calculations are performed in integer whole cents, rounding halves away from zero. PayPal Developer Platform & MCP Agent Toolkit (Decision 0021): Leverages PayPal's official Agent Toolkit MCP server (@paypal/[email protected]) via Node.js npx with tool access strictly restricted to --tools=invoices.create. Due dates and post-creation updates are managed directly via PayPal's REST API. Duplicate Prevention via Idempotency (Decision 0017): Each deal and choice gets one fixed PayPal invoice number. Before creating, the agent looks for a draft with that number, and after any failure it looks again, so a retry or a double click finds the same draft instead of making a second one. Cryptographic Fingerprinted Approval: Generated a SHA-256 hash of all tool arguments and execution sequences. The executor verifies the hash at runtime, so a plan changed after approval never runs. A per-deal lock makes a double click run one approval after the other. Comprehensive Security Alignment: Mapped code defenses against the OWASP Top 10 for LLM Applications (2025), the OWASP Agentic Top 10 (ASI), and the MAST multi-agent failure taxonomy.

Challenges we ran into

Applying strict software engineering discipline to generative AI and real financial transactions surfaced eight major challenges during development, recorded in our failure register and review logs:

The Decimal Tail Bug: In initial parser tests, digits following a decimal point were erroneously parsed as separate whole numbers (e.g. "2.5% off" parsed as 5%, "40.125 dollars" read as $125). We updated the normalizer to drop numbers situated inside decimals and mark the field as unsure, asking the seller rather than guessing. Invoice Search Returning Single Mismatched Results: When PayPal's invoice search returned a single result, the client originally returned it even if the invoice number belonged to a different invoice. We enforced strict equality matching, returning "not found" unless the returned invoice number matches exactly. Scaled Amount Read-Back Parsing: When reading back invoice amounts from PayPal, the reader stripped negative signs, treating "-0.50" as +50 cents, and silently truncated fractional decimals. We implemented a strict parser requiring digits only, at most two decimal places, and no signs, failing loudly if unexpected values appear. Concurrency and Interrupted Connections: Rapid double-clicking on the "Approve" button could trigger concurrent execution runs colliding on local state, while closing the browser tab severed HTTP request contexts mid-run. We serialized deal execution using in-memory mutexes and detached a dedicated 3-minute background execution context. Unicode Evasion in Reply Checker: The reply validator initially checked only ASCII digits '0'-'9'. Full-width Unicode digits ("２０"), fractions ("½"), and non-Western currency symbols bypassed the check. We replaced ASCII filtering with Unicode category checks (unicode.IsNumber and the Unicode currency-symbol category) across all scripts. Fragile Toolkit Duplicate Matching: The system initially identified duplicate draft attempts by matching the text string "DUPLICATE" in toolkit errors. When error wording varied, repeat runs reported false failures. We refactored error handling to query PayPal directly for the deterministic invoice number after any creation failure, adopting existing drafts cleanly. Silent Dropping of Double-Discount Findings: In live evaluations, when an original list price was missing from extracted quotes during a discounted price increase, email 08's $6.00 double-discount warning was silently dropped. We updated the logic to ask the seller for clarification whenever the baseline price cannot be determined. Real Buyers Write Short Answers: While rehearsing the demo, a buyer reply of just "Option 2 please" came back "unclear", because the reader only saw the buyer's line, not the choices we had sent. We now give the reader our own choices ahead of the buyer's words, require the acceptance to be quoted from the buyer's own words, and let the seller confirm or correct the reading with one tap. Checked live: "Option 2 please" and "The bigger order works for us" are both read as the Quantity choice, and "let me think about it" still asks. Each challenge was resolved by committing a failing test first, followed by the corrective implementation.

Accomplishments that we're proud of

1-Command Zero-Key Proof (go run ./cmd/proof): Delivered an automated scorecard that runs in seconds without any API key, AI call or PayPal call, because the recorded AI answers ship in the repository: Reading: 0 wrong-but-sure, 20 / 20 emails right, 144 / 144 fields right, 2 / 2 prompt injections safely ignored, 4 / 4 must-ask items asked, 0 unnecessary questions, and 6 / 6 mutation tests passed. Money: 16 / 16 profits matched within 1 cent, 16 / 16 alert levels correct, and 0 false alarms on healthy deals. Safety: 12 / 12 tampered plans blocked with 0 unauthorized PayPal calls made, 1 / 1 modified plan blocked after approval, 1 draft created with 0 duplicates on repeat runs, 7 / 7 reply-checker evasion attacks rejected, and 1 / 1 wrong AI planner proposal blocked. The End-to-End Agentic Commerce Loop: Successfully linked customer email negotiations, profit auditing, principled counter-proposals, AI response drafting, customer agreement parsing, cryptographic human approval, and PayPal Sandbox draft invoice creation with field-by-field verification. Zero Floats for Financial Calculations: All money arithmetic is in integer whole cents, with halves rounded away from zero; decimal strings from PayPal are read back strictly, without floats. 82 Automated Claim Checks: Each of the 82 product claims in the README is tied to a passing test, a line of code or a line of the proof output, checked by script (check_claims.py) and then read by hand against its evidence.

What we learned

LLM-Modulo is Essential for Financial AI: LLMs excel at linguistic interpretation, contextual reasoning, and polite drafting, but they should never be trusted with arithmetic, quote validation, or raw tool execution. Keeping math and permissions in deterministic code eliminates entire classes of AI failure modes. Model Confidence is Unreliable: An LLM saying it is confident in its own reading proves nothing. True verification requires multi-model consensus, exact string quoting against the source text, and strict schema parsing. Principled Negotiation Beats Concession: As taught in Never Split the Difference and Getting to Yes, giving in on price to "be friendly" does not create enduring customer goodwill. Providing clear, objective reasons and trading value (such as volume for shipping or speed for discounts) builds more sustainable merchant relationships.

What's next for margin-check

The seller's own tone: let the seller choose short or long, warm or formal, or learn it from two or three of their own past replies, so the drafted reply sounds like them. A vague "make it sound like me" doesn't work, so the choices will be explicit. One-tap answers for the buyer: a link in the seller's email where the buyer taps the choice they want, so there is nothing for the AI to misread at all. Direct Inbox Integration: Expand beyond pasted email threads to optional, read-only OAuth integrations with Gmail and Microsoft Outlook. Multi-Currency Support: Expand beyond US dollars and US sandbox accounts to support multi-currency international commerce with configurable exchange rate safeguards. Native PayPal Early-Payment Rules: Transition the early-payment discount option to PayPal's native conditional rules once available for sandbox automation. Merchant Memory & Negotiation Analytics: Maintain private, local deal histories to identify repeat customer patterns, calculate aggregate margin recovery, and highlight chronic margin leaks over time.

Built With

Share this project:

Updates

Submission history