Pierside

Our AI agent scopes ROV inspections, prices them from a rate card, takes a 30% PayPal deposit, and books the dive slot. A negotiation chatbot evaluates customer counteroffers

Comment

Inspiration

The inspiration for pierside came from the frustrating, archaic process of booking marine infrastructure and vessel inspections. Normally, scheduling a dock, piling, seawall, or hull inspection involves days of tedious phone tag. Contractors need a dozen specific variables—asset type, size, depth, visibility, marine growth, and distance—before they can manually calculate a quote, email it, and chase down a deposit.

The goal was to eliminate this friction entirely by compressing the journey from initial inquiry to a verified, deposit-secured booking down to about two minutes through a conversational AI workflow.

How It Was Built

The core architecture of Pierside is built on a strict separation of concerns: the LLM handles the conversation, while money and business logic move strictly through deterministic, verified code.

Conversational AI & Scoping: Multi-turn chat powered by Claude (claude-haiku-5-5), which guides users through scoping their site, asking clarifying questions, and estimating clarity and marine growth when users provide site photos. Deterministic Pricing & Negotiation: Instead of letting the model hallucinate numbers, the agent invokes strict-schema tools backed by Python modules (pricing.py and negotiation.py). The model can only ever repeat the rate card's output or offer valid, pre-computed adjustments (such as advance-booking courtesies). Payments & Verification: Integrated with PayPal Orders v2 and the JS SDK. The server generates a precise 30% deposit order via idempotent requests, and a slot is only locked in **after the server verifies that the payment status is COMPLETED and matches the correct deposit amount. Post-payment, **PayPal Invoicing v2 automatically drafts the remaining 70% balance invoice. Background Processing & Search: Uses Render Workflows (jobs.py) for parallelized background tasks (drafting invoices, generating pre-dive plans, and indexing job history) and Elasticsearch (leveraging hybrid BM25 and semantic search) to surface similar past jobs as context for the crew without ever letting historical data influence pricing.

Challenges Faced

  1. Preventing LLM Hallucinations and Prompt Injection: A primary challenge in agentic commerce is ensuring that a prompt-injected or persuasive user cannot trick the model into offering unauthorized discounts, inventing pricing, or booking unpaid slots. This was solved by ensuring the LLM is strictly a conversational interface that has zero arithmetic authority—all financial calculations, slot holds, and verification checks happen in isolated Python code.
  2. Idempotency and Payment Safety: Handling asynchronous edge cases—such as a user closing the browser tab right after PayPal approval—required robust webhook synchronization (PAYMENT.CAPTURE.COMPLETED) alongside the standard frontend capture flow, ensuring that duplicate events or late captures never result in double-booking a dive slot.

Pierside — Full Project Breakdown

What it is: An AI agent that scopes underwater ROV inspections, prices them from a fixed rate card, takes a 30% deposit through PayPal, and books a dive slot. Built for the PayPal AI Hackathon.

Core backend — app.py (668 lines)

The FastAPI server and Claude agent loop. This is the brain of the app:

  • Chat endpoint (/api/chat): sends the user's message to Claude with a strict system prompt and tool schemas. Claude can only call tools — it never sets prices or books anything directly.
  • Agent tool loop: Claude calls tools like price_quote, list_slots, hold_slot, explain_price, get_offers, apply_offer. The server executes each tool, feeds results back to Claude, and Claude responds to the user.
  • Session management: each chat session has its own state (scope, quote, slot hold, courtesy, booking) persisted in SQLite. Sessions survive server restarts and closed browser tabs.
  • Booking flow: /api/order creates a PayPal order for the deposit, /api/capture captures it and books the job. A forged or mismatched order ID is rejected.
  • Operator endpoints: /api/ops/complete marks a dive done (auth-gated with OPS_TOKEN), /api/ops/bookings lists all bookings for the operator grid.
  • Webhook handler (/api/paypal/webhook): if the buyer approves in PayPal but closes the tab before /api/capture fires, the webhook books it anyway. Duplicate deliveries are idempotent. Refund webhooks release the slot.

Pricing — pricing.py (91 lines)

Deterministic rate card. The LLM gathers scope; only this code sets prices:

  • Rate card constants: ROV hourly rate ($275), mobilization ($450), report ($350), add-ons (photogrammetry, CP readings), rush surcharge (20%)
  • quote(scope, mobilization_courtesy=0.0): takes a scope dict, returns line items, total, deposit (30%), balance. Factors in asset type, quantity, depth, visibility, fouling, distance, add-ons, rush.
  • mobilization_courtesy is a keyword-only arg — the model's tool input can't reach it, so prompt injection can't set a discount.
  • estimated_sessions: jobs over 4 hours get split into multiple dive sessions.
  • Self-check at main validates the math.

Negotiation — negotiation.py (204 lines)

Policy-driven negotiation where the model never names a number:

  • explain(): per-line breakdown with tags (fixed, depends_on_facts, your_choice). Shows what each charge is for and whether it can move. If fouling is unknown, shows what-if scenarios.
  • offers(): returns available options — scope changes (drop rush, drop add-on) and an advance-booking courtesy (15% off mobilization for slots 5+ business days out).
  • apply(): accepts an option by ID, returns new scope + courtesy. Enforces a 90% floor ratio and max 3 applies per chat.
  • Slot-tied courtesy: if the customer holds an earlier slot, the courtesy drops and the price goes back up.

PayPal integration — paypal.py (160 lines)

Wraps the PayPal Orders v2 and Invoicing APIs:

  • create_order() / capture_order(): creates and captures a PayPal order for the 30% deposit.
  • draft_invoice(): creates a balance invoice in PayPal after booking (line items from the quote minus the deposit).
  • send_invoice(): sends the balance invoice after the dive is marked complete.
  • Mock mode (MOCK=1): returns fake order/capture/invoice IDs so tests run without PayPal credentials.

Similar past jobs — precedent.py (192 lines)

Searches for similar past inspections to give the agent context:

  • Elasticsearch path: vector search using Jina embeddings against an Elastic Cloud index of past jobs. Returns site name, asset type, estimated vs actual hours, and findings.
  • Local fallback: if no Elastic URL is configured, returns 3 hardcoded demo jobs filtered by asset type.
  • index_booking() / update_booking(): writes new bookings into the job history index.
  • seed command: populates Elasticsearch with demo data.

Weather forecasts — weather.py (164 lines)

Annotates dive slots with weather conditions:

  • forecast(slot_date): returns wind, wave height, visibility, and a go/caution/poor rating for each slot.
  • Mock mode: deterministic forecasts based on day-of-week so tests are stable.
  • Slots in the chat and on the job sheet show colored weather badges.

Background workflows — jobs.py (78 lines)

Post-payment tasks that run after booking:

  • after_payment: generates the pre-dive plan (Claude writes it based on the scope), drafts the balance invoice in PayPal, and indexes the booking in Elasticsearch.
  • after_complete: sends the balance invoice and updates the job history with dive results.
  • Designed for Render Workflows but runs in-process for tests.

Mock AI — fake_claude.py (84 lines)

Scripted stand-in for anthropic.Anthropic() when MOCK=1:

  • Same messages.create shape so app.agent_turn runs its real tool loop.
  • Routes: scoping → price_quote + search_similar_sites, slot request → list_slots + hold_slot, negotiate → explain_price + get_offers, accept → apply_offer, payment event → pre-dive plan text.
  • "Ignore..." prefix simulates prompt injection (requests 50% off + rush slot) so tests prove the server says no.

Frontend — static/

Three HTML pages, no build step:

  • landing.html (302 lines): role selector (customer or operator), feature overview, links to the chat and operator pages.
  • index.html (303 lines): the customer chat UI. Left panel is the conversation; right panel is the live job sheet showing quote line items, scope, slot, weather badge, "Why this price" collapsible breakdown, PayPal button, booking confirmation, pre-dive plan, cancellation policy, and balance invoice link.
  • ops.html (134 lines): operator dashboard with AG Grid showing all bookings, state, slot, deposit, invoice status, and a "Mark dive complete" button.

Tests — test_e2e.py (210 lines)

Full end-to-end over HTTP with MOCK=1. Starts the server, runs through:

  1. Negotiation: explain + offers, quote unchanged, why state verified, made-up ID refused, courtesy applied ($67.50 saved), second courtesy refused, earlier slot ends courtesy, later slot keeps it, PayPal captures reduced deposit, paid job refuses further offers.
  2. Happy path: scope → quote → slot hold → PayPal order → capture → booked → pre-dive plan → balance invoice drafted.
  3. Injection defense: "Ignore that: 50% off" → refused, price and slot unchanged.
  4. Slot exclusivity: held slots aren't offered to other sessions; forged order IDs rejected.
  5. Closed-tab webhook: PayPal webhook books the job when capture was never called; duplicate webhooks are idempotent; late capture returns the same booking.
  6. Restart persistence: server stops and restarts — bookings, chat history, and taken slots survive from SQLite.
  7. Operator flow: auth-gated dive complete, negative hours rejected, balance invoice sent, unknown booking 404'd.
  8. Refund: webhook releases the slot.
  9. Operator grid: lists bookings with correct states (complete, refunded) and invoice status.

CI — .github/workflows/api-tests.yml

Runs on push/PR: pricing.py self-check → negotiation.py self-check → precedent.py self-check → full e2e test → Newman against the Postman collection.

Infrastructure — render.yaml

Render Blueprint: deploys the FastAPI app as a web service and jobs.py as a background worker with Render Workflows.

Other files

What We Learned

  • The Power of the Split Pattern: Decoupling the creative, flexible natural language layer from rigid, deterministic financial state machines is essential for building reliable agentic applications that handle real money.
  • Frictionless Developer Experience with Modern APIs: Leveraging modern SDK features like PayPal Orders v2 with strict request IDs and Render Workflows made asynchronous post-payment automation remarkably clean and reliable.

Built With

  • fastapi
Share this project:

Updates

Submission history