Closira AI-Powered Customer Support Workflow

This repository contains a Python-based customer support workflow for Bloom Aesthetics Clinic. It implements a 4-stage conversational AI system designed to answer FAQs using Standard Operating Procedures (SOP), qualify customer leads, detect and escalate sensitive issues to human agents, and generate a final conversation summary.

The chatbot operates on a robust, stateful pipeline structured into four logical stages:

1. Stage 1: Escalation & Sentiment Check (Pre-processing): Blocks unsafe or out-of-scope interactions (e.g. complaints, medical advice, pricing negotiations) and triggers immediate human handoff.
2. Stage 2: FAQ Grounding (SOP Retrieval): Answers customer queries using only facts present in the local sop.json. Non-SOP topics are caught and logged as gaps.
3. Stage 3: Lead Qualification: Triggers when a booking intent is identified. Gathers details on the desired service, prior treatment history, and scheduling availability.
4. Stage 4: Session Summary (Post-processing): At the end of the session, compiles user intent, extracted lead details, SOP gaps, and recommended actions.

• Python 3.8 or higher.
• An active API Key for Google Gemini, OpenAI, or Anthropic (Optional: the system features a built-in Mock provider allowing full execution without API keys).

1. Clone or navigate to the project directory:

   cd "e:\intern\closira chatbot"

2. Create and activate the virtual environment (venv):

   • Windows (PowerShell):

     python -m venv .venv
     .\.venv\Scripts\Activate.ps1

   • Mac/Linux:

     python3 -m venv .venv
     source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure Environment Variables: Copy the example environment file and open it to insert your API key(s):

   cp .env.example .env

   Open the newly created .env file and input your credentials, e.g.:

   GEMINI_API_KEY=your_gemini_api_key_here
   LLM_PROVIDER=gemini
   LLM_MODEL=gemini-2.5-flash

   (If no keys are provided, or you run into API quota limits, you can open .env and set LLM_PROVIDER=mock so the workflow runs offline using the built-in mock LLM engine).

This script simulates the 5 required customer interaction scenarios, outputs step-by-step logs, and saves transcripts as markdown files under the test_transcripts/ directory.

python run_tests.py

Start a real-time conversation session in your terminal with live execution logs showing the 4-stage pipeline outputs.

python cli.py

Type exit or quit to end the chat and output the session summary.

The automated tests output transcripts to the test_transcripts/ folder, which demonstrate the following behaviors:

1. 1_in_sop_question.md: Botox price inquiries answered accurately from the SOP.
2. 2_out_of_scope_question.md: Unrelated queries (e.g. laser hair removal) flagged as out-of-scope, culminating in an escalation on the 3rd consecutive gap.
3. 3_escalation_trigger.md: User frustration, anger, or complaints triggering instant human handoffs.
4. 4_lead_qualification.md: A structured booking flow collecting services, prior experience, and scheduling availability.
5. 5_conversation_summary.md: Complete generation of structured data at the end of a session.

• JSON Response Integrity: LLMs can occasionally return malformed JSON. The client attempts to clean output formatting (e.g., stripping markdown code block backticks), but in a production environment, strong schema enforcement like Pydantic models or Structured Outputs APIs should be fully configured.
• Context Window Management: For long conversations, sending the entire message history can become expensive and hit token limits. A sliding context window or summarization strategy should be used for production.
• Mock Coverage: While mock mode perfectly simulates the 5 target scenarios, it utilizes rule-based keyword matching. For dynamic conversation branches, a live API connection is required.