bookly/README.md

Bookly

Try it live: https://bookly.codyborders.com

A conversational customer support agent for a fictional online bookstore.

The agent handles two depth use cases (order status and returns) and one breadth use case (policy questions) over a vanilla HTML chat UI, backed by Anthropic Claude with a four-layer guardrail strategy. The full agent design rationale lives in DESIGN.md. Take a deeper dive at https://bookly.codyborders.com/architecture.

Try it yourself

Open https://bookly.codyborders.com and chat with the agent. The store is fictional and the data is fake — use the orders below to walk through the happy paths and the failure modes the guardrails are designed to catch.

Orders in the database

Order ID	Customer	Email	Status	Notes
BK-10042	Sarah Chen	sarah.chen@example.com	delivered	The Goldfinch + Sapiens, $36.98. Delivered 15 days ago — inside the 30-day return window.
BK-10089	James Murphy	james.murphy@example.com	shipped	Project Hail Mary, $18.99. Shipped 4 days ago, not yet delivered.
BK-10103	Sarah Chen	sarah.chen@example.com	processing	Tomorrow, and Tomorrow, and Tomorrow, $17.99. Ordered yesterday, not yet shipped.
BK-9871	Maria Gonzalez	maria.gonzalez@example.com	delivered	The Midnight Library, $15.99. Delivered 55 days ago — past the 30-day window.

Things to try

Happy paths

• "What's the status of BK-10089?" then provide the email — should show the shipped status and tracking number.
• "I want to return BK-10042. My email is sarah.chen@example.com." — should walk through eligibility, summarize the refund terms, ask for confirmation, then issue an RMA.
• "How do I reset my password?" — should quote the verbatim FAQ entry.
• "What's your shipping policy?" — same pattern, verbatim quote.

Sad paths the agent should handle gracefully

• "Where is my order?" with no order ID — should ask for the BK-prefixed ID.
• Sarah Chen has two orders — say "I want to return my order" with her email and the agent should ask which one.
• "I want to return BK-10089" — should refuse because the order has not been delivered yet.
• "I want to return BK-9871" with Maria's email — should refuse because the order is past the 30-day window.
• Provide the wrong email for an order — the agent should say it can't find a match (privacy: no enumeration of which IDs exist).

Things the agent should refuse

• "Recommend me a good mystery novel."
• "Which book should I read next?"
• "Can you change my shipping address?"
• "I want to dispute a charge on my credit card."

In every refusal case the agent uses the same template and offers to redirect you to something it can help with.

Stack

• Python 3.11+, FastAPI, Uvicorn
• Anthropic Claude (Sonnet) with prompt caching
• Vanilla HTML / CSS / JS chat frontend (no build step)
• Pytest

Setup

python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cp .env.example .env
# edit .env and set ANTHROPIC_API_KEY

Run locally

./venv/bin/uvicorn server:app --host 127.0.0.1 --port 8014

Then open http://127.0.0.1:8014 in a browser.

Tests

./venv/bin/python -m pytest tests/ -v

Tests mock the Anthropic client, so no API key or network access is required.

Project layout

agent.py        System prompt, guardrails (layers 1, 2, 4), agentic loop
tools.py        Tool schemas, handlers, SessionGuardState (layer 3)
mock_data.py    Orders, return policy, FAQ policies
server.py       FastAPI app: /api/chat, /health, static mount
config.py       pydantic-settings config loaded from .env
static/         index.html, style.css, chat.js
tests/          test_tools.py, test_agent.py
deploy/         systemd unit + nginx site config for the production droplet

Design

See DESIGN.md for the architecture, conversation design, hallucination and safety controls, and production-readiness tradeoffs.