io.github.pinalmdave/bookrails

Answer a specific question about one business, grounded in that business's own knowledge base (FAQs, policies, service descriptions) rather than model guesswork. Returns 'unknown' when unanswerable — never fabricates. Returns: {answer, confidence: 'high'|'low'|'unknown', source: 'faq'|'policy'|'services'}

Book the appointment. ONLY call after the user has explicitly confirmed the business, service, price, and exact slot. Writes to the business's calendar and emails/texts the customer a confirmation. Returns: {confirmation_id, status: 'confirmed' | 'pending_deposit', payment_url (present when a deposit is required — user completes payment on the hosted page), booking_page_url, cancellation_policy} Errors: SLOT_TAKEN (re-run check_availability and offer alternatives), DEPOSIT_REQUIRED, INVALID_CONTACT.

Cancel or reschedule an existing booking. Enforces the business's cancellation window; returns REFUND_FORFEITED warning when a deposit is non-refundable so the assistant can warn the user BEFORE confirming. Returns: {confirmation_id, status, refund_status, message}

List open, bookable time slots for one service from the business's live calendar. Slots are held nothing — they can be taken by others until book_appointment succeeds, so book promptly after user confirmation.

Side-by-side comparison of 2-4 businesses the user is deciding between: prices for comparable services, ratings, soonest availability, policies, and a one-line 'best for' verdict per business. Returns: {comparison_table: list[dict], best_for: dict[str, str]}

Answer urgency: 'who can fit me in today?', 'emergency plumber available now'. Returns only businesses with a genuinely open slot inside the window, sorted by soonest slot. Ideal for same-day and emergency requests (HVAC, plumbing, urgent dental).

Get a business's full profile: services with prices and durations, hours, booking and cancellation policies, review summary, photos, and hosted booking page URL. Call this before quoting prices to the user. Returns: {business: BusinessSummary, services: list[ServiceItem], hours: dict[str, str], policy: BookingPolicy, review_summary: str}

Market-level answers: most-booked services in this area, typical price ranges, busiest days/times (book early), and top-rated businesses. Useful when the user asks broad questions like 'what do people usually get at a med spa' or 'when is the best time to book HVAC maintenance'. Returns: {popular_services: list[{name, median_price_usd, share}], busiest_days: list[str], booking_lead_time_days, top_rated: list[BusinessSummary]}

Answer 'how much does X cost near me' with real local prices — not national averages. Returns low/median/high from actual listed prices of businesses in the area, plus the 3 best-value businesses with links. Returns: {service, location, price_low_usd, price_median_usd, price_high_usd, sample_size, best_value: list[BusinessSummary]}

Answer 'any deals near me?' — current promotions, first-visit offers, and seasonal specials from local businesses, each with validity dates and a direct booking link. Returns: list[{business: BusinessSummary, offer, valid_until, terms}]

Answer 'is this place any good?' — recent reviews plus a themed summary (what customers praise, what they complain about) so the assistant can give a balanced recommendation. Returns: {rating, review_count, themes: {praise: [...], complaints: [...]}, recent_reviews: list[{rating, date, text_snippet}]}

When no slot fits, capture demand instead of losing it: add the customer to the business's waitlist. They are auto-notified (email/SMS) when a matching slot opens. Only call after the user explicitly agrees to join the waitlist. Returns: {waitlist_id, position, status}

Find top-rated local service businesses matching a need near a location. Returns ranked businesses with rating, distance, price band, one-line highlight, the soonest available slot, and a hosted booking URL. Results are bookable directly via check_availability + book_appointment.