Spicy Cosmo AI Receptionist

Local-first AI receptionist and appointment-booking showcase for service businesses. This project demonstrates a guest-facing chat workflow, deterministic scheduler actions, and a private scheduler/admin view.

What it does

• Handles customer booking requests through a guest-facing chat interface
• Suggests alternate appointment slots when requested times are unavailable
• Supports same-session rescheduling and cancellation flows with confirmation
• Captures unsupported or manual-request cases for front-desk follow-up
• Connects a receptionist workflow to deterministic scheduler actions
• Runs as a local-first stack with a templated public guest deployment profile

Deployment template

• Public booking page example: https://example.com
• Public API origin example: https://api.example.com
• Voice API example: https://voice.example.com
• Admin API example: https://adminapi.example.com

Replace these example domains with your own deployment targets before use.

Key project highlights

• Local-first architecture with optional public guest access
• Appointment-based business workflow
• Natural-language handling for names, dates, next-weekday phrasing, and approximate times like 2ish
• Separate guest-facing flow and private admin/scheduler workflow
• Regression and smoke tooling included for repeatable verification
• Config templates included for adapting the project to a new business profile

Verified behaviors

• standard supported booking
• alternate-slot booking
• mixed supported and unsupported request handling
• same-session cancel with confirmation
• same-session reschedule with confirmation
• booking quota cap within one session
• manual request capture for unsupported services
• natural phrasing support such as next Wednesday, 2ish, and curly-apostrophe name input

Architecture overview

Core services:

• 8890 — scheduler HTTP service
• 8891 — private admin UI static server
• 8892 — receptionist chat API
• 8893 — LLM bridge
• 8894 — public guest UI static server
• 11434 — Ollama

Main application files:

• spicy_cosmo_api.py — receptionist API
• spicy_ollama_api.py — LLM bridge
• scheduler_api.py — scheduler wrapper
• scheduler_http.py — scheduler HTTP server

UI paths:

• ui/spicy_cosmo_chat.html — local/LAN receptionist chat UI source
• ui/scheduler_view.html — private admin/scheduler UI
• ui_public/index.html — public guest UI template

Operations and validation

Useful commands:

• ./citadel-spicy start
• ./citadel-spicy check
• ./citadel-spicy restart
• ./citadel-spicy smoke
• ./ops/reset_trial_state.sh

Helpful operational files:

• ops/install_goodfellas_public_guest.sh — example public guest UI install helper
• ops/regression_smoke.sh — regression smoke helper
• config_template/ — public-safe configuration templates

Scope

This repository is a showcase / prototype package. It is not presented as a hardened SaaS platform. Review and adapt configuration, auth, networking, and deployment settings before production use.

Why this project matters

This project showcases hands-on work in:

• AI-assisted workflow design
• local-first system architecture
• Python-based service orchestration
• debugging and regression discipline
• real-world booking and scheduling logic
• deployment support for small-business appointment workflows

Public-safety note

Runtime logs, private state, local machine paths, exports, backups, and live deployment identifiers are intentionally excluded or templated.