Autonomous Procurement Agent#

Stop overpaying. Stop missing fraud. Every week, procurement teams lose money because a supplier's quote arrived as a messy email, a merged-cell SAP export, or a PDF scan with OCR artifacts. The unit price got misread. The line math was wrong. Nobody caught it — until the invoice was already paid.

Autonomous Procurement Agent handles every format. Every currency. With fraud detection that actually blocks, not just warns.

---

First-Use Initialisation#

Before processing any quotes, configure your environment:

bash

# Required in production — server refuses to start without this
export LS_WEBHOOK_SECRET="your_ls_webhook_secret"

# Optional: enables GPT-4o fallback for messy formats (plain-text, OCR scans).
# Without this, Engine 2 is skipped and only regex parsing runs.
# All parsing is LOCAL without this key.
export OPENAI_API_KEY="sk-..."

# Optional: override default ports and directories
export PARSER_DATA_DIR="$HOME/.procurement-agent-data"
export PROCU_WEBHOOK_PORT="3002"

# Start the webhook server (receives LS payment events → activates license)
node webhook-handler.js &
# → Listening on http://localhost:3002/webhook/lemon-squeezy

Never log raw quote content, vendor names, or API keys to stdout. The parser runs entirely locally unless OPENAI_API_KEY is set — in which case Privacy Shield scrubs all sensitive fields before any external call.

---

Quick Reference#

SituationActionSupplier quote in plain-text or emailParse with Engine 1 (regex, <50ms)Invoice has merged cells or OCR artifactsEngine 2 triggers automatically (if OPENAI_API_KEY set)F1 math error detected on a line itemLine blocked → whole PO escalated to REVIEWF2 price spike >20% above historical avgCRITICAL alert → auto-blockF3 duplicate PO within 7 daysWarning logged → duplicate flaggedCircuit breaker trips 2 consecutive approver failuresSafety-Freeze → all POs held for manual approvalLemon Squeezy payment confirmedWebhook writes to data/licenses.json automaticallyHigh-value PO (>$50,000) needs LLM hintgenerateLLMHint() called with USD-normalised structureReceiving a quote without API keyEngine 1 regex only; no external calls made

---

Installation#

Via ClawHub (recommended)#

bash

clawhub install autonomous-procurement-agent

Manual#

bash

git clone https://github.com/arya-openclaw/autonomous-procurement-agent.git \
  ~/.openclaw/skills/autonomous-procurement-agent
cd ~/.openclaw/skills/autonomous-procurement-agent
npm install

Lemon Squeezy Webhook Setup#

1. Go to your Lemon Squeezy dashboard → Webhooks
2. Add endpoint: https://your-domain.com/webhook/lemon-squeezy
3. Copy the signing secret → set as LS_WEBHOOK_SECRET
4. For local dev, use ngrok: ngrok http 3002

No PayPal: Lemon Squeezy handles global tax (VAT/GST included in price) and supports Payoneer / World First / Wise payouts. PayPal is not supported due to high dispute fees and China-market account ban risk.

---

Environment Variables#

VariableRequiredDefaultDescriptionLS_WEBHOOK_SECRETYes (prod)—HMAC-SHA256 signing secret from LS dashboard. Server refuses to start without it.OPENAI_API_KEYNo—OpenAI key. Only needed for Engine 2 (GPT-4o fallback). Without it, all parsing is local.LS_PRO_VARIANT_IDNo999Lemon Squeezy variant ID for Pro tierLS_ENT_VARIANT_IDNo2999Lemon Squeezy variant ID for Enterprise tierPARSER_DATA_DIRNo~/.procurement-agent-dataLocal directory for license DB + historical price baselineCB_THRESHOLDNo2Circuit breaker failures before Safety-Freeze triggersPROCU_WEBHOOK_PORTNo3002Webhook HTTP server portLS_STORE_IDNo—Lemon Squeezy store ID for API callsLS_API_KEYNo—Lemon Squeezy API key for license managementOPENAI_MODELNogpt-4oOpenAI model for LLM fallback (only when OPENAI_API_KEY is set)EXCHANGE_RATE_URLNoFixed tableOptional live FX rate API endpointHISTORICAL_PRICE_URLNoBuilt-in baselineOptional API for F2 historical price baselinePROCU_ALLOWED_TIERNo—Dev override — bypasses webhook signature check. Do not use in production.

---

Scenarios#

1. Cross-Platform Quote Reconciliation

A manufacturing firm receives quotes from three suppliers: one as a CSV export, one as a plain-text email ("qty 8 × $2,800 = $22,400"), one as a scanned PDF forwarded from a WhatsApp photo. Procurement Agent normalises all three to a structured comparison table in under a second.

2. B2B Finance Real-Time Risk Audit

Finance receives a €47,000 PO from a long-term vendor. The line items all check out mathematically — but F2 flags that the unit price for the primary component is 34% above the 6-month average. The PO is auto-blocked before the CFO's signature is requested.

---

How F1 / F2 / F3 Work#

F1 — Calculation Verification (Enterprise only)#

Every line: unit_price × quantity ≠ line_total → line blocked, PO escalated.

Supplier quotes "8 units × $2,800 = $22,400". You calculate the same. F1 checks it. Supplier made a $200 arithmetic error in their favour. You catch it before signing.

F1 runs automatically on every parse. No configuration required.

F2 — Price Spike Detection (Enterprise only)#

Current price > historical average × 1.20 → CRITICAL alert + auto-block.

Ball bearings purchased at $12/unit for 6 months. New quote: $16/unit. F2 flags this 34% spike before approval.

Baseline import (one-time):

bash

node self-healing-parser.js import-baseline ./historical-prices.json

F3 — Duplicate Quote Detection (Enterprise only)#

Same vendor + same total + within 7 days → duplicate warning.

Two RFQs sent. Supplier responds twice. Finance processes both. F3 catches the duplicate before you pay twice.

---

Architecture#

text

Supplier quote (any format)
        │
        ▼
┌─────────────────────┐
│  Engine 1: Regex   │  ← JSON → HTML table → CSV → Plain text
│  (< 50ms)          │
└──────────┬──────────┘
           │
    confidence < 0.5
    or messy format
           │
           ▼
┌─────────────────────┐
│  Engine 2: GPT-4o  │  ← Only runs if OPENAI_API_KEY is set.
│  (opt-in LLM)       │     All parsing is LOCAL without this key.
└──────────┬──────────┘
           │
    ┌──────┴──────┐
    │  Risk Engine │
    │  F1 / F2 /F3 │  ← Enterprise only
    └──────┬──────┘
           │
    risk_score > 0.5
           │
           ▼
    STATUS: REJECTED_FOR_REVIEW

---

Parsing Output Format#

Every parseQuote() call returns a structured result. Here is the canonical schema:

javascript

{
  "vendor_name":     "Acme Corp",
  "po_number":       "PO-2024-0041",
  "currency":        "USD",
  "line_items": [
    {
      "description":    "Industrial Ball Bearing",
      "quantity":       8,
      "unit_price":     2800.00,
      "line_total":     22400.00,
      "extracted_raw":  "8 × $2,800 = $22,400",
      "f1_flag":        false,      // true if unit_price × qty ≠ line_total
      "f2_flag":        false,      // true if >20% above historical avg
      "anomaly":        false,
      "reason":         null
    }
  ],
  "subtotal":        22000.00,
  "tax":             1980.00,
  "total":           23980.00,
  "confidence_score": 0.93,
  "parse_method":    "regex",      // "regex" | "llm_fallback" | "html_table" | "csv"
  "is_llm_fallback": false,
  "variant_detected": null,         // "V4" | "V8" | "V10" | null
  "anomaly_flags":   [],
  "fraud_flags":     [],
  "recommendation":  "AUTO_APPROVED", // "AUTO_APPROVED" | "REVIEW" | "REJECT"
  "safety_freeze":   false,
  "llm_error":       null
}

Confidence Tiers#

ScoreTierMeaning≥ 0.85highRegex pipeline succeeded cleanly≥ 0.5mediumPartial parse; some fields recovered< 0.5lowUnparseable; falls back to LLM or returns error

---

Privacy Shield (v1.0.0+)#

Before any quote content is sent to the OpenAI API, it passes through a Privacy Shield — a local regex sanitiser that runs before the HTTP request is made. No external services are called; no data leaves your server at this stage.

FieldReplacementExampleSupplier/vendor name[VENDOR_MASKED]``"Acme Corp" → "[VENDOR_MASKED]"Monetary amounts[AMOUNT_MASKED]``"$1,234.56" → "[AMOUNT_MASKED]"Email / phone / fax[PII_REDACTED]``"john@corp.com" → "[PII_REDACTED]"Street addresses[PII_REDACTED]``"12 Main St, Shenzhen" → "[PII_REDACTED]"

Trigger: Privacy Shield is applied automatically whenever OPENAI_API_KEY is set and a quote requires GPT-4o fallback. It does not run in local-only regex mode.

GPT-4o receives enough structure to validate mathematical consistency and detect anomalies — but cannot see actual supplier prices or identities.

---

License Tiers#

FreePro ($9.99/mo)Enterprise ($29.99/mo)Quotes/month20500UnlimitedParse formatsJSON, HTML, CSVAll formatsAll formats + LLM fallbackF1 Calculation Check——✅ Built inF2 Price Spike Detection——✅ Built inF3 Duplicate Detection——✅ Built inCNY→USD Normalization—✅✅Approval flow——✅Safety-Freeze circuit breaker——✅Historical price baseline——✅Priority support——✅

---

Generic Setup (Other AI Agents)#

For Claude Code, Codex, Copilot, or other agents:

bash

mkdir -p ~/.openclaw/skills/autonomous-procurement-agent
git clone https://github.com/arya-openclaw/autonomous-procurement-agent.git \
  ~/.openclaw/skills/autonomous-procurement-agent
cd ~/.openclaw/skills/autonomous-procurement-agent
npm install

Parse a quote:

bash

node self-healing-parser.js parse '<content>' [format] '{"email":"user@example.com"}'

---

Periodic Review#

Review flagged POs regularly:

bash

# List POs with active risk flags
grep -r "REJECTED_FOR_REVIEW\|CRITICAL\|suspicious" \
  ~/.procurement-agent-data/logs/ 2>/dev/null | tail -20

# Check Safety-Freeze status
grep "Safety-Freeze" ~/.procurement-agent-data/logs/*.log 2>/dev/null | tail -5

# Check license DB health
cat ~/.procurement-agent-data/data/licenses.json | python3 -m json.tool

---

Best Practices#

1. Always set LS_WEBHOOK_SECRET in production — the server refuses to start without it. There is no bypass flag.
2. OPENAI_API_KEY is opt-in — without it, no quote content is ever sent to any external API.
3. Import your historical price baseline before using F2 — without it, F2 spike detection uses a conservative built-in table.
4. Keep PARSER_DATA_DIR backed up — data/licenses.json is the source of truth for all license state.
5. Do not commit data/licenses.json to git — add it to .gitignore. License records are per-install, not per-repo.
6. Use PROCU_ALLOWED_TIER only in local dev — it bypasses webhook signature validation and must never be set in production.
7. Webhook logs are sanitised automatically — sanitize() redacts email addresses and API keys before writing logs.
8. Review F2 spike alerts promptly — F2 is silent until a spike is detected; configure alerts accordingly.

---

Multi-Agent Support#

OpenClaw (primary platform)#

Activation: Automatic skill loading via ClawHub or workspace injection.

Detection: Trigger keywords ( supplier quote, purchase order, vendor risk, price spike, fraud detection, approval escalation, safety freeze).

Claude Code / Codex#

Activation: Direct invocation or workspace injection.

Setup: Copy skill to ~/.openclaw/skills/autonomous-procurement-agent, then:

bash

export LS_WEBHOOK_SECRET="your_secret"
node webhook-handler.js &

Detection: Chat triggers listed above.

GitHub Copilot#

Activation: Manual prompt — reference the skill directly in conversation.

Setup: Add to .github/copilot-instructions.md:

markdown

## Procurement Fraud Detection

When reviewing vendor quotes or purchase orders, use:
~/.openclaw/skills/autonomous-procurement-agent/self-healing-parser.js

Set OPENAI_API_KEY for LLM fallback on messy formats.

Agent-Agnostic Guidance#

Regardless of agent, apply Autonomous Procurement Agent when:

1. A supplier quote arrives in a non-standard format — plain-text, merged-cell spreadsheet, OCR scan.
2. Multiple currencies need to be compared — CNY, USD, EUR reconciliation.
3. A high-value PO needs validation — F1 catches math errors; F2 catches price spikes.
4. Duplicate invoices are suspected — F3 detects same-vendor same-total within 7 days.
5. Approval thresholds need to be enforced automatically — Safety-Freeze on circuit breaker trip.