Initial commit

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.venv
+venv
+__pycache__
+*.pyc
+.env
+data/db
+data/chroma
+.pytest_cache
+.mypy_cache
+test

.env.example

@@ -0,0 +1,24 @@
+# ReplyFlow — Hugging Face Space secrets
+
+# Required for real LLM answers (set as Space Secret)
+OPENAI_API_KEY=
+
+# Optional models
+OPENAI_MODEL=gpt-4o-mini
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+
+# App
+APP_NAME=ReplyFlow
+APP_ENV=production
+SECRET_KEY=change-me-in-space-secrets
+DEMO_BUSINESS_NAME=Nordic Paper Solutions
+DEMO_TIMEZONE=Europe/Paris
+
+# Optional integrations
+CALCOM_API_KEY=
+CALCOM_EVENT_TYPE_ID=
+CALCOM_USERNAME=
+WHATSAPP_TOKEN=
+WHATSAPP_PHONE_NUMBER_ID=
+WHATSAPP_VERIFY_TOKEN=replyflow-verify
+HANDOFF_WEBHOOK_URL=

.gitignore

@@ -0,0 +1,11 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+data/db/
+data/chroma/
+!data/knowledge/
+*.log
+*.db
+.DS_Store

Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Hugging Face Spaces listens on 7860.
+# JSON vector fallback only (no Chroma sidecar on Spaces).
+ENV PORT=7860 \
+    PYTHONUNBUFFERED=1 \
+    APP_ENV=production \
+    DATABASE_URL=sqlite+aiosqlite:///./data/db/replyflow.db \
+    CHROMA_PATH=./data/chroma \
+    KNOWLEDGE_PATH=./data/knowledge
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p /app/data/db /app/data/chroma /app/data/knowledge \
+    && chmod -R 777 /app/data
+
+EXPOSE 7860
+
+CMD ["sh", "-c", \
+    "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860}"]

README.md

@@ -1,10 +1,56 @@
----
-title: ReplyFlow
-emoji: 🏢
-colorFrom: gray
-colorTo: pink
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: ReplyFlow
+emoji: 💬
+colorFrom: green
+colorTo: yellow
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# ReplyFlow
+
+Multilingual customer chatbot for **web** (and WhatsApp-ready):
+grounded RAG answers, lead capture, appointment slots, and
+human handoff.
+
+**Demo claim:** 60% of questions handled without a human,
+appointment booking 24/7.
+
+## Demo business
+
+Fictional SME **Nordic Paper Solutions** (FAQ EN / FR / RU).
+Safe for demos — no real customer data.
+
+## How to use
+
+1. Open **Live demo** and ask about products, pricing, delivery.
+2. Try booking a call (demo slots if Cal.com is not set).
+3. Check **Dashboard** for conversations and KPIs.
+4. Optional: embed with `<script src="/widget.js" defer></script>`.
+
+## Space secrets
+
+In **Settings → Variables and secrets**, set:
+
+| Name | Value |
+|------|--------|
+| `OPENAI_API_KEY` | your OpenAI key (**Secret**) |
+| `OPENAI_MODEL` | `gpt-4o-mini` |
+| `OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` |
+
+Optional:
+
+| Name | Purpose |
+|------|--------|
+| `CALCOM_API_KEY` + `CALCOM_EVENT_TYPE_ID` | real bookings |
+| `WHATSAPP_TOKEN` + `WHATSAPP_PHONE_NUMBER_ID` | WhatsApp channel |
+| `HANDOFF_WEBHOOK_URL` | notify humans on escalation |
+
+Without OpenAI, ReplyFlow still runs in **demo mode** (local
+embeddings + template grounded answers).
+
+## Stack
+
+FastAPI · RAG (JSON vector store on Spaces) · OpenAI · Cal.com
+hooks · WhatsApp webhook · SQLite

app/__init__.py

@@ -0,0 +1 @@
+"""ReplyFlow application package."""

app/api/__init__.py

@@ -0,0 +1 @@
+"""API routers package."""

app/api/appointments.py

@@ -0,0 +1,105 @@
+"""Appointment booking API."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.db import get_db
+from app.models import Appointment, Conversation, Message
+from app.schemas import AppointmentResponse, BookAppointmentRequest
+from app.services import calcom
+
+router = APIRouter(prefix="/api/appointments", tags=["appointments"])
+
+
+@router.get("/slots")
+async def list_slots() -> dict:
+    """List next available slots."""
+    slots = await calcom.get_available_slots(3)
+    return {"slots": slots}
+
+
+@router.post("/book", response_model=AppointmentResponse)
+async def book_appointment(
+    body: BookAppointmentRequest,
+    db: AsyncSession = Depends(get_db),
+) -> AppointmentResponse:
+    """Book a selected slot for a conversation."""
+    result = await db.execute(
+        select(Conversation)
+        .where(Conversation.id == body.conversation_id)
+        .options(
+            selectinload(Conversation.lead),
+            selectinload(Conversation.appointment),
+        )
+    )
+    conv = result.scalar_one_or_none()
+    if conv is None:
+        raise HTTPException(status_code=404, detail="Not found")
+
+    if conv.appointment is not None:
+        raise HTTPException(
+            status_code=400, detail="Already booked"
+        )
+
+    name = body.attendee_name
+    email = body.attendee_email
+    if conv.lead:
+        name = name or conv.lead.name
+        email = email or conv.lead.email
+
+    booked = await calcom.book_slot(
+        slot_start=body.slot_start,
+        slot_end=body.slot_end,
+        attendee_name=name,
+        attendee_email=email,
+    )
+
+    appt = Appointment(
+        conversation_id=conv.id,
+        slot_start=booked["slot_start"],
+        slot_end=booked["slot_end"],
+        attendee_name=name,
+        attendee_email=email,
+        external_id=booked.get("external_id"),
+        status=booked.get("status", "confirmed"),
+    )
+    conv.appointment_booked = True
+    db.add(appt)
+
+    confirm = {
+        "en": (
+            f"Your meeting is confirmed for "
+            f"{body.slot_start}. See you then!"
+        ),
+        "fr": (
+            f"Votre rendez-vous est confirmé pour "
+            f"{body.slot_start}. À bientôt !"
+        ),
+        "ru": (
+            f"Встреча подтверждена на {body.slot_start}. "
+            f"До связи!"
+        ),
+    }
+    lang = conv.language if conv.language in confirm else "en"
+    message = confirm[lang]
+    db.add(
+        Message(
+            conversation_id=conv.id,
+            role="assistant",
+            content=message,
+            language=lang,
+            grounded=True,
+        )
+    )
+    await db.commit()
+    await db.refresh(appt)
+
+    return AppointmentResponse(
+        id=appt.id,
+        slot_start=appt.slot_start,
+        slot_end=appt.slot_end,
+        status=appt.status,
+        message=message,
+    )

app/api/chat.py

@@ -0,0 +1,47 @@
+"""Chat API routes."""
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import get_db
+from app.schemas import (
+    ChatMessageRequest,
+    ChatMessageResponse,
+    ChatStartResponse,
+)
+from app.services.chat import handle_user_message, start_conversation
+from app.services.language import normalize_ui_language
+
+router = APIRouter(prefix="/api/chat", tags=["chat"])
+
+
+@router.post("/start", response_model=ChatStartResponse)
+async def chat_start(
+    ui_language: str = "en",
+    db: AsyncSession = Depends(get_db),
+) -> ChatStartResponse:
+    """Start a new web conversation."""
+    lang = normalize_ui_language(ui_language)
+    conv, greeting = await start_conversation(
+        db, channel="web", ui_language=lang
+    )
+    return ChatStartResponse(
+        conversation_id=conv.id,
+        greeting=greeting,
+        language=lang,
+    )
+
+
+@router.post("/message", response_model=ChatMessageResponse)
+async def chat_message(
+    body: ChatMessageRequest,
+    db: AsyncSession = Depends(get_db),
+) -> ChatMessageResponse:
+    """Send a user message and receive the bot reply."""
+    data = await handle_user_message(
+        db,
+        conversation_id=body.conversation_id,
+        message=body.message,
+        ui_language=normalize_ui_language(body.ui_language),
+    )
+    return ChatMessageResponse(**data)

app/api/conversations.py

@@ -0,0 +1,168 @@
+"""Conversation history API."""
+
+from __future__ import annotations
+
+import csv
+import io
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.db import get_db
+from app.models import Conversation, Lead, Message
+from app.schemas import (
+    ConversationDetail,
+    ConversationSummary,
+    MessageOut,
+)
+from app.services.leads import lead_to_dict
+
+router = APIRouter(
+    prefix="/api/conversations", tags=["conversations"]
+)
+
+
+@router.get("", response_model=list[ConversationSummary])
+async def list_conversations(
+    db: AsyncSession = Depends(get_db),
+) -> list[ConversationSummary]:
+    """List conversations newest first."""
+    msg_count = (
+        select(
+            Message.conversation_id,
+            func.count(Message.id).label("cnt"),
+        )
+        .group_by(Message.conversation_id)
+        .subquery()
+    )
+    result = await db.execute(
+        select(Conversation, Lead, msg_count.c.cnt)
+        .outerjoin(Lead, Lead.conversation_id == Conversation.id)
+        .outerjoin(
+            msg_count, msg_count.c.conversation_id == Conversation.id
+        )
+        .order_by(Conversation.created_at.desc())
+        .limit(200)
+    )
+    rows = result.all()
+    items: list[ConversationSummary] = []
+    for conv, lead, count in rows:
+        items.append(
+            ConversationSummary(
+                id=conv.id,
+                channel=conv.channel,
+                language=conv.language,
+                status=conv.status,
+                handed_off=conv.handed_off,
+                appointment_booked=conv.appointment_booked,
+                resolved_without_human=conv.resolved_without_human,
+                message_count=int(count or 0),
+                created_at=conv.created_at,
+                lead_name=lead.name if lead else None,
+            )
+        )
+    return items
+
+
+@router.get(
+    "/{conversation_id}",
+    response_model=ConversationDetail,
+)
+async def get_conversation(
+    conversation_id: int,
+    db: AsyncSession = Depends(get_db),
+) -> ConversationDetail:
+    """Get one conversation with messages."""
+    result = await db.execute(
+        select(Conversation)
+        .where(Conversation.id == conversation_id)
+        .options(
+            selectinload(Conversation.messages),
+            selectinload(Conversation.lead),
+            selectinload(Conversation.appointment),
+        )
+    )
+    conv = result.scalar_one_or_none()
+    if conv is None:
+        raise HTTPException(status_code=404, detail="Not found")
+
+    appointment: dict[str, Any] | None = None
+    if conv.appointment:
+        appointment = {
+            "slot_start": conv.appointment.slot_start,
+            "slot_end": conv.appointment.slot_end,
+            "status": conv.appointment.status,
+            "attendee_name": conv.appointment.attendee_name,
+            "attendee_email": conv.appointment.attendee_email,
+        }
+
+    return ConversationDetail(
+        id=conv.id,
+        channel=conv.channel,
+        language=conv.language,
+        status=conv.status,
+        handed_off=conv.handed_off,
+        appointment_booked=conv.appointment_booked,
+        resolved_without_human=conv.resolved_without_human,
+        created_at=conv.created_at,
+        messages=[
+            MessageOut(
+                id=m.id,
+                role=m.role,
+                content=m.content,
+                language=m.language,
+                grounded=m.grounded,
+                created_at=m.created_at,
+            )
+            for m in conv.messages
+        ],
+        lead=lead_to_dict(conv.lead),
+        appointment=appointment,
+    )
+
+
+@router.get("/{conversation_id}/export")
+async def export_conversation(
+    conversation_id: int,
+    db: AsyncSession = Depends(get_db),
+) -> StreamingResponse:
+    """Export conversation messages as CSV."""
+    result = await db.execute(
+        select(Conversation)
+        .where(Conversation.id == conversation_id)
+        .options(selectinload(Conversation.messages))
+    )
+    conv = result.scalar_one_or_none()
+    if conv is None:
+        raise HTTPException(status_code=404, detail="Not found")
+
+    buffer = io.StringIO()
+    writer = csv.writer(buffer)
+    writer.writerow(
+        ["id", "role", "language", "grounded", "created_at", "content"]
+    )
+    for m in conv.messages:
+        writer.writerow(
+            [
+                m.id,
+                m.role,
+                m.language or "",
+                m.grounded if m.grounded is not None else "",
+                m.created_at.isoformat(),
+                m.content,
+            ]
+        )
+    buffer.seek(0)
+    return StreamingResponse(
+        iter([buffer.getvalue()]),
+        media_type="text/csv",
+        headers={
+            "Content-Disposition": (
+                f'attachment; filename="conversation_{conversation_id}.csv"'
+            )
+        },
+    )

app/api/dashboard.py

@@ -0,0 +1,90 @@
+"""Dashboard metrics API."""
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import get_db
+from app.models import Conversation, Lead, UnansweredQuestion
+from app.schemas import DashboardStats
+
+router = APIRouter(prefix="/api/dashboard", tags=["dashboard"])
+
+
+@router.get("/stats", response_model=DashboardStats)
+async def dashboard_stats(
+    db: AsyncSession = Depends(get_db),
+) -> DashboardStats:
+    """Aggregate KPIs for the operator dashboard."""
+    total = await db.scalar(
+        select(func.count(Conversation.id))
+    ) or 0
+    resolved = await db.scalar(
+        select(func.count(Conversation.id)).where(
+            Conversation.resolved_without_human.is_(True)
+        )
+    ) or 0
+    appointments = await db.scalar(
+        select(func.count(Conversation.id)).where(
+            Conversation.appointment_booked.is_(True)
+        )
+    ) or 0
+    handed = await db.scalar(
+        select(func.count(Conversation.id)).where(
+            Conversation.handed_off.is_(True)
+        )
+    ) or 0
+    unanswered = await db.scalar(
+        select(func.count(UnansweredQuestion.id))
+    ) or 0
+    leads_complete = await db.scalar(
+        select(func.count(Lead.id)).where(Lead.complete.is_(True))
+    ) or 0
+
+    channel_rows = (
+        await db.execute(
+            select(
+                Conversation.channel,
+                func.count(Conversation.id),
+            ).group_by(Conversation.channel)
+        )
+    ).all()
+    language_rows = (
+        await db.execute(
+            select(
+                Conversation.language,
+                func.count(Conversation.id),
+            ).group_by(Conversation.language)
+        )
+    ).all()
+
+    recent = (
+        await db.execute(
+            select(UnansweredQuestion)
+            .order_by(UnansweredQuestion.created_at.desc())
+            .limit(10)
+        )
+    ).scalars().all()
+
+    rate = (resolved / total * 100.0) if total else 0.0
+
+    return DashboardStats(
+        total_conversations=int(total),
+        resolved_without_human=int(resolved),
+        resolution_rate=round(rate, 1),
+        appointments_booked=int(appointments),
+        handed_off=int(handed),
+        unanswered_count=int(unanswered),
+        leads_complete=int(leads_complete),
+        by_channel={c: int(n) for c, n in channel_rows},
+        by_language={lang: int(n) for lang, n in language_rows},
+        recent_unanswered=[
+            {
+                "id": q.id,
+                "conversation_id": q.conversation_id,
+                "question": q.question,
+                "created_at": q.created_at.isoformat(),
+            }
+            for q in recent
+        ],
+    )

app/api/knowledge.py

@@ -0,0 +1,55 @@
+"""Knowledge base ingestion API."""
+
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, File, UploadFile
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import get_settings
+from app.db import get_db
+from app.models import KnowledgeDoc
+from app.schemas import KnowledgeIngestResponse
+from app.services.rag import get_knowledge_store, ingest_path
+
+router = APIRouter(prefix="/api/knowledge", tags=["knowledge"])
+
+
+@router.get("/status")
+async def knowledge_status() -> dict:
+    """Return current knowledge chunk count."""
+    store = get_knowledge_store()
+    return {"chunk_count": store.chunk_count}
+
+
+@router.post(
+    "/ingest",
+    response_model=KnowledgeIngestResponse,
+)
+async def ingest_upload(
+    file: UploadFile = File(...),
+    db: AsyncSession = Depends(get_db),
+) -> KnowledgeIngestResponse:
+    """Upload and ingest a knowledge document."""
+    settings = get_settings()
+    target_dir = Path(settings.knowledge_path)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    filename = Path(file.filename or "upload.txt").name
+    dest = target_dir / filename
+    content = await file.read()
+    dest.write_bytes(content)
+
+    source = dest.suffix.lower().lstrip(".") or "text"
+    count = await ingest_path(dest, source)
+    db.add(
+        KnowledgeDoc(
+            filename=filename,
+            source_type=source,
+            chunk_count=count,
+        )
+    )
+    await db.commit()
+    return KnowledgeIngestResponse(
+        filename=filename,
+        chunk_count=count,
+        message=f"Ingested {count} chunks from {filename}",
+    )

app/api/whatsapp.py

@@ -0,0 +1,140 @@
+"""WhatsApp Business Cloud API webhook."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import get_settings
+from app.db import get_db
+from app.models import Conversation
+from app.services.chat import handle_user_message, start_conversation
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/whatsapp", tags=["whatsapp"])
+
+
+@router.get("/webhook")
+async def verify_webhook(
+    hub_mode: str = Query(alias="hub.mode", default=""),
+    hub_verify_token: str = Query(
+        alias="hub.verify_token", default=""
+    ),
+    hub_challenge: str = Query(
+        alias="hub.challenge", default=""
+    ),
+) -> Any:
+    """Meta webhook verification handshake."""
+    settings = get_settings()
+    if (
+        hub_mode == "subscribe"
+        and hub_verify_token == settings.whatsapp_verify_token
+    ):
+        return int(hub_challenge) if hub_challenge.isdigit() else hub_challenge
+    raise HTTPException(status_code=403, detail="Verification failed")
+
+
+@router.post("/webhook")
+async def receive_webhook(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> dict[str, str]:
+    """Receive inbound WhatsApp messages."""
+    payload = await request.json()
+    settings = get_settings()
+
+    try:
+        entries = payload.get("entry", [])
+        for entry in entries:
+            for change in entry.get("changes", []):
+                value = change.get("value", {})
+                messages = value.get("messages", [])
+                for msg in messages:
+                    if msg.get("type") != "text":
+                        continue
+                    wa_from = msg.get("from", "")
+                    text = msg.get("text", {}).get("body", "")
+                    if not wa_from or not text:
+                        continue
+                    await _process_incoming(
+                        db,
+                        wa_from=wa_from,
+                        text=text,
+                        settings=settings,
+                    )
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("WhatsApp webhook error: %s", exc)
+
+    return {"status": "ok"}
+
+
+async def _process_incoming(
+    db: AsyncSession,
+    *,
+    wa_from: str,
+    text: str,
+    settings: Any,
+) -> None:
+    result = await db.execute(
+        select(Conversation).where(
+            Conversation.channel == "whatsapp",
+            Conversation.external_id == wa_from,
+            Conversation.status == "active",
+        )
+    )
+    conv = result.scalar_one_or_none()
+    if conv is None:
+        conv, _greeting = await start_conversation(
+            db,
+            channel="whatsapp",
+            ui_language="en",
+            external_id=wa_from,
+        )
+
+    data = await handle_user_message(
+        db,
+        conversation_id=conv.id,
+        message=text,
+        ui_language=conv.language or "en",
+    )
+    await send_whatsapp_text(wa_from, data["reply"])
+
+
+async def send_whatsapp_text(to: str, body: str) -> None:
+    """Send a WhatsApp text message if credentials exist."""
+    settings = get_settings()
+    if not settings.has_whatsapp:
+        logger.info(
+            "WhatsApp demo send to=%s body=%s", to, body[:120]
+        )
+        return
+
+    url = (
+        f"https://graph.facebook.com/v20.0/"
+        f"{settings.whatsapp_phone_number_id}/messages"
+    )
+    headers = {
+        "Authorization": f"Bearer {settings.whatsapp_token}",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "messaging_product": "whatsapp",
+        "to": to,
+        "type": "text",
+        "text": {"body": body[:4000]},
+    }
+    async with httpx.AsyncClient(timeout=20) as client:
+        response = await client.post(
+            url, headers=headers, json=payload
+        )
+        if response.status_code >= 400:
+            logger.error(
+                "WhatsApp send failed: %s %s",
+                response.status_code,
+                response.text,
+            )

app/config.py

@@ -0,0 +1,71 @@
+"""Application settings loaded from environment."""
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime configuration for ReplyFlow."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    app_name: str = "ReplyFlow"
+    app_env: str = "production"
+    secret_key: str = "change-me"
+    public_base_url: str = "http://localhost:7860"
+
+    database_url: str = (
+        "sqlite+aiosqlite:///./data/db/replyflow.db"
+    )
+    chroma_path: str = "./data/chroma"
+    knowledge_path: str = "./data/knowledge"
+
+    openai_api_key: str = ""
+    openai_model: str = "gpt-4o-mini"
+    openai_embedding_model: str = "text-embedding-3-small"
+
+    calcom_api_key: str = ""
+    calcom_event_type_id: str = ""
+    calcom_username: str = ""
+
+    whatsapp_token: str = ""
+    whatsapp_phone_number_id: str = ""
+    whatsapp_verify_token: str = "replyflow-verify"
+    whatsapp_app_secret: str = ""
+
+    handoff_webhook_url: str = ""
+
+    demo_business_name: str = "Nordic Paper Solutions"
+    demo_timezone: str = "Europe/Paris"
+
+    @property
+    def has_openai(self) -> bool:
+        """True when an OpenAI API key is configured."""
+        return bool(self.openai_api_key.strip())
+
+    @property
+    def has_calcom(self) -> bool:
+        """True when Cal.com credentials are configured."""
+        return bool(
+            self.calcom_api_key.strip()
+            and self.calcom_event_type_id.strip()
+        )
+
+    @property
+    def has_whatsapp(self) -> bool:
+        """True when WhatsApp credentials are configured."""
+        return bool(
+            self.whatsapp_token.strip()
+            and self.whatsapp_phone_number_id.strip()
+        )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return cached settings instance."""
+    return Settings()

app/db.py

@@ -0,0 +1,37 @@
+"""Async database session helpers."""
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from app.config import get_settings
+from app.models import Base
+
+settings = get_settings()
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,
+)
+
+SessionLocal = async_sessionmaker(
+    engine,
+    expire_on_commit=False,
+    class_=AsyncSession,
+)
+
+
+async def init_db() -> None:
+    """Create tables if they do not exist."""
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """Yield a database session."""
+    async with SessionLocal() as session:
+        yield session

app/main.py

@@ -0,0 +1,128 @@
+"""ReplyFlow FastAPI application entrypoint."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from app.api import (
+    appointments,
+    chat,
+    conversations,
+    dashboard,
+    knowledge,
+    whatsapp,
+)
+from app.config import get_settings
+from app.db import init_db
+from app.schemas import HealthResponse
+from app.services.rag import get_knowledge_store, ingest_directory
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+)
+logger = logging.getLogger("replyflow")
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    """Initialize DB and knowledge base on startup."""
+    settings = get_settings()
+    Path("data/db").mkdir(parents=True, exist_ok=True)
+    Path(settings.chroma_path).mkdir(parents=True, exist_ok=True)
+    Path(settings.knowledge_path).mkdir(parents=True, exist_ok=True)
+
+    await init_db()
+    store = get_knowledge_store()
+    if store.chunk_count == 0:
+        kb_path = Path(settings.knowledge_path)
+        count = await ingest_directory(kb_path)
+        logger.info("Seeded knowledge base with %s chunks", count)
+    else:
+        logger.info(
+            "Knowledge base already loaded (%s chunks)",
+            store.chunk_count,
+        )
+    yield
+
+
+settings = get_settings()
+app = FastAPI(
+    title=settings.app_name,
+    version="1.0.0",
+    description=(
+        "Multilingual customer chatbot for web and WhatsApp "
+        "with RAG, lead qualification, and appointments."
+    ),
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(chat.router)
+app.include_router(appointments.router)
+app.include_router(conversations.router)
+app.include_router(dashboard.router)
+app.include_router(knowledge.router)
+app.include_router(whatsapp.router)
+
+static_dir = Path(__file__).parent / "static"
+app.mount(
+    "/static",
+    StaticFiles(directory=str(static_dir)),
+    name="static",
+)
+
+
+@app.get("/api/health", response_model=HealthResponse)
+async def health() -> HealthResponse:
+    """Health check and integration flags."""
+    store = get_knowledge_store()
+    return HealthResponse(
+        status="ok",
+        app=settings.app_name,
+        openai=settings.has_openai,
+        calcom=settings.has_calcom,
+        whatsapp=settings.has_whatsapp,
+        knowledge_chunks=store.chunk_count,
+    )
+
+
+@app.get("/")
+async def home() -> FileResponse:
+    """Landing page."""
+    return FileResponse(static_dir / "index.html")
+
+
+@app.get("/chat")
+async def chat_page() -> FileResponse:
+    """Full-page chat demo."""
+    return FileResponse(static_dir / "chat.html")
+
+
+@app.get("/dashboard")
+async def dashboard_page() -> FileResponse:
+    """Operator dashboard."""
+    return FileResponse(static_dir / "dashboard.html")
+
+
+@app.get("/widget.js")
+async def widget_script() -> FileResponse:
+    """Embeddable chat widget script."""
+    return FileResponse(
+        static_dir / "widget" / "replyflow-widget.js",
+        media_type="application/javascript",
+    )

app/models.py

@@ -0,0 +1,214 @@
+"""SQLAlchemy models for conversations and leads."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+)
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    Mapped,
+    mapped_column,
+    relationship,
+)
+
+
+class Base(DeclarativeBase):
+    """Declarative base."""
+
+
+class Conversation(Base):
+    """A chat session on web or WhatsApp."""
+
+    __tablename__ = "conversations"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    channel: Mapped[str] = mapped_column(
+        String(32), default="web"
+    )
+    language: Mapped[str] = mapped_column(
+        String(8), default="en"
+    )
+    status: Mapped[str] = mapped_column(
+        String(32), default="active"
+    )
+    external_id: Mapped[Optional[str]] = mapped_column(
+        String(128), nullable=True
+    )
+    failure_streak: Mapped[int] = mapped_column(
+        Integer, default=0
+    )
+    resolved_without_human: Mapped[bool] = mapped_column(
+        Boolean, default=False
+    )
+    handed_off: Mapped[bool] = mapped_column(
+        Boolean, default=False
+    )
+    appointment_booked: Mapped[bool] = mapped_column(
+        Boolean, default=False
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=datetime.utcnow,
+        onupdate=datetime.utcnow,
+    )
+
+    messages: Mapped[list["Message"]] = relationship(
+        back_populates="conversation",
+        cascade="all, delete-orphan",
+        order_by="Message.created_at",
+    )
+    lead: Mapped[Optional["Lead"]] = relationship(
+        back_populates="conversation",
+        uselist=False,
+        cascade="all, delete-orphan",
+    )
+    appointment: Mapped[Optional["Appointment"]] = (
+        relationship(
+            back_populates="conversation",
+            uselist=False,
+            cascade="all, delete-orphan",
+        )
+    )
+
+
+class Message(Base):
+    """Single message in a conversation."""
+
+    __tablename__ = "messages"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    conversation_id: Mapped[int] = mapped_column(
+        ForeignKey("conversations.id"), index=True
+    )
+    role: Mapped[str] = mapped_column(String(16))
+    content: Mapped[str] = mapped_column(Text)
+    language: Mapped[Optional[str]] = mapped_column(
+        String(8), nullable=True
+    )
+    grounded: Mapped[Optional[bool]] = mapped_column(
+        Boolean, nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow
+    )
+
+    conversation: Mapped["Conversation"] = relationship(
+        back_populates="messages"
+    )
+
+
+class Lead(Base):
+    """Prospect qualification data collected in chat."""
+
+    __tablename__ = "leads"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    conversation_id: Mapped[int] = mapped_column(
+        ForeignKey("conversations.id"), unique=True
+    )
+    name: Mapped[Optional[str]] = mapped_column(
+        String(128), nullable=True
+    )
+    need: Mapped[Optional[str]] = mapped_column(
+        Text, nullable=True
+    )
+    budget: Mapped[Optional[str]] = mapped_column(
+        String(64), nullable=True
+    )
+    contact_channel: Mapped[Optional[str]] = mapped_column(
+        String(64), nullable=True
+    )
+    email: Mapped[Optional[str]] = mapped_column(
+        String(256), nullable=True
+    )
+    phone: Mapped[Optional[str]] = mapped_column(
+        String(64), nullable=True
+    )
+    complete: Mapped[bool] = mapped_column(
+        Boolean, default=False
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=datetime.utcnow,
+        onupdate=datetime.utcnow,
+    )
+
+    conversation: Mapped["Conversation"] = relationship(
+        back_populates="lead"
+    )
+
+
+class Appointment(Base):
+    """Booked meeting slot."""
+
+    __tablename__ = "appointments"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    conversation_id: Mapped[int] = mapped_column(
+        ForeignKey("conversations.id"), unique=True
+    )
+    slot_start: Mapped[str] = mapped_column(String(64))
+    slot_end: Mapped[str] = mapped_column(String(64))
+    attendee_name: Mapped[Optional[str]] = mapped_column(
+        String(128), nullable=True
+    )
+    attendee_email: Mapped[Optional[str]] = mapped_column(
+        String(256), nullable=True
+    )
+    external_id: Mapped[Optional[str]] = mapped_column(
+        String(128), nullable=True
+    )
+    status: Mapped[str] = mapped_column(
+        String(32), default="confirmed"
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow
+    )
+
+    conversation: Mapped["Conversation"] = relationship(
+        back_populates="appointment"
+    )
+
+
+class UnansweredQuestion(Base):
+    """Question the bot could not answer from KB."""
+
+    __tablename__ = "unanswered_questions"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    conversation_id: Mapped[int] = mapped_column(
+        ForeignKey("conversations.id"), index=True
+    )
+    question: Mapped[str] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow
+    )
+
+
+class KnowledgeDoc(Base):
+    """Ingested knowledge document metadata."""
+
+    __tablename__ = "knowledge_docs"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    filename: Mapped[str] = mapped_column(String(256))
+    source_type: Mapped[str] = mapped_column(String(32))
+    chunk_count: Mapped[int] = mapped_column(Integer, default=0)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow
+    )

app/schemas.py

@@ -0,0 +1,133 @@
+"""Pydantic request/response schemas."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ChatStartResponse(BaseModel):
+    """New conversation payload."""
+
+    conversation_id: int
+    greeting: str
+    language: str
+
+
+class ChatMessageRequest(BaseModel):
+    """Incoming user message."""
+
+    conversation_id: int
+    message: str = Field(min_length=1, max_length=4000)
+    ui_language: str = "en"
+
+
+class ChatMessageResponse(BaseModel):
+    """Bot reply payload."""
+
+    conversation_id: int
+    reply: str
+    language: str
+    grounded: bool
+    lead: Optional[dict[str, Any]] = None
+    suggested_slots: Optional[list[dict[str, str]]] = None
+    handed_off: bool = False
+    appointment_booked: bool = False
+
+
+class BookAppointmentRequest(BaseModel):
+    """Confirm a suggested slot."""
+
+    conversation_id: int
+    slot_start: str
+    slot_end: str
+    attendee_name: Optional[str] = None
+    attendee_email: Optional[str] = None
+
+
+class AppointmentResponse(BaseModel):
+    """Booked appointment confirmation."""
+
+    id: int
+    slot_start: str
+    slot_end: str
+    status: str
+    message: str
+
+
+class ConversationSummary(BaseModel):
+    """List item for conversation history."""
+
+    id: int
+    channel: str
+    language: str
+    status: str
+    handed_off: bool
+    appointment_booked: bool
+    resolved_without_human: bool
+    message_count: int
+    created_at: datetime
+    lead_name: Optional[str] = None
+
+
+class MessageOut(BaseModel):
+    """Message in conversation detail."""
+
+    id: int
+    role: str
+    content: str
+    language: Optional[str]
+    grounded: Optional[bool]
+    created_at: datetime
+
+
+class ConversationDetail(BaseModel):
+    """Full conversation with messages."""
+
+    id: int
+    channel: str
+    language: str
+    status: str
+    handed_off: bool
+    appointment_booked: bool
+    resolved_without_human: bool
+    created_at: datetime
+    messages: list[MessageOut]
+    lead: Optional[dict[str, Any]] = None
+    appointment: Optional[dict[str, Any]] = None
+
+
+class DashboardStats(BaseModel):
+    """Dashboard KPI metrics."""
+
+    total_conversations: int
+    resolved_without_human: int
+    resolution_rate: float
+    appointments_booked: int
+    handed_off: int
+    unanswered_count: int
+    leads_complete: int
+    by_channel: dict[str, int]
+    by_language: dict[str, int]
+    recent_unanswered: list[dict[str, Any]]
+
+
+class KnowledgeIngestResponse(BaseModel):
+    """Result of knowledge ingestion."""
+
+    filename: str
+    chunk_count: int
+    message: str
+
+
+class HealthResponse(BaseModel):
+    """Service health and feature flags."""
+
+    status: str
+    app: str
+    openai: bool
+    calcom: bool
+    whatsapp: bool
+    knowledge_chunks: int

app/services/__init__.py

@@ -0,0 +1 @@
+"""Services package."""

app/services/calcom.py

@@ -0,0 +1,163 @@
+"""Cal.com appointment integration with demo fallback."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+from uuid import uuid4
+
+import httpx
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+async def get_available_slots(
+    count: int = 3,
+) -> list[dict[str, str]]:
+    """Return upcoming available slots."""
+    settings = get_settings()
+    if settings.has_calcom:
+        try:
+            slots = await _fetch_calcom_slots(count)
+            if slots:
+                return slots
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Cal.com slots failed: %s", exc)
+    return _demo_slots(count)
+
+
+async def book_slot(
+    *,
+    slot_start: str,
+    slot_end: str,
+    attendee_name: Optional[str],
+    attendee_email: Optional[str],
+) -> dict[str, Any]:
+    """Create a booking via Cal.com or demo store."""
+    settings = get_settings()
+    if settings.has_calcom:
+        try:
+            return await _book_calcom(
+                slot_start=slot_start,
+                slot_end=slot_end,
+                attendee_name=attendee_name or "Guest",
+                attendee_email=attendee_email
+                or "guest@example.com",
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Cal.com booking failed: %s", exc)
+
+    return {
+        "external_id": f"demo-{uuid4().hex[:10]}",
+        "slot_start": slot_start,
+        "slot_end": slot_end,
+        "status": "confirmed",
+        "demo": True,
+    }
+
+
+def _demo_slots(count: int) -> list[dict[str, str]]:
+    now = datetime.now(timezone.utc).replace(
+        minute=0, second=0, microsecond=0
+    )
+    slots: list[dict[str, str]] = []
+    cursor = now + timedelta(days=1)
+    while len(slots) < count:
+        if cursor.weekday() < 5 and cursor.hour in (10, 14, 16):
+            end = cursor + timedelta(minutes=30)
+            slots.append(
+                {
+                    "start": cursor.isoformat(),
+                    "end": end.isoformat(),
+                    "label": cursor.strftime(
+                        "%a %d %b %Y · %H:%M UTC"
+                    ),
+                }
+            )
+        cursor += timedelta(hours=2)
+    return slots
+
+
+async def _fetch_calcom_slots(count: int) -> list[dict[str, str]]:
+    settings = get_settings()
+    start = datetime.now(timezone.utc)
+    end = start + timedelta(days=14)
+    url = "https://api.cal.com/v1/slots"
+    params = {
+        "apiKey": settings.calcom_api_key,
+        "eventTypeId": settings.calcom_event_type_id,
+        "startTime": start.isoformat(),
+        "endTime": end.isoformat(),
+    }
+    async with httpx.AsyncClient(timeout=20) as client:
+        response = await client.get(url, params=params)
+        response.raise_for_status()
+        data = response.json()
+
+    slots: list[dict[str, str]] = []
+    raw_slots = data.get("slots") or data
+    if isinstance(raw_slots, dict):
+        for day_slots in raw_slots.values():
+            if not isinstance(day_slots, list):
+                continue
+            for item in day_slots:
+                start_s = item.get("time") or item.get("start")
+                if not start_s:
+                    continue
+                start_dt = datetime.fromisoformat(
+                    start_s.replace("Z", "+00:00")
+                )
+                end_dt = start_dt + timedelta(minutes=30)
+                slots.append(
+                    {
+                        "start": start_dt.isoformat(),
+                        "end": end_dt.isoformat(),
+                        "label": start_dt.strftime(
+                            "%a %d %b %Y · %H:%M UTC"
+                        ),
+                    }
+                )
+                if len(slots) >= count:
+                    return slots
+    return slots[:count]
+
+
+async def _book_calcom(
+    *,
+    slot_start: str,
+    slot_end: str,
+    attendee_name: str,
+    attendee_email: str,
+) -> dict[str, Any]:
+    settings = get_settings()
+    url = "https://api.cal.com/v1/bookings"
+    payload = {
+        "eventTypeId": int(settings.calcom_event_type_id),
+        "start": slot_start,
+        "responses": {
+            "name": attendee_name,
+            "email": attendee_email,
+        },
+        "timeZone": settings.demo_timezone,
+        "language": "en",
+        "metadata": {},
+    }
+    params = {"apiKey": settings.calcom_api_key}
+    async with httpx.AsyncClient(timeout=20) as client:
+        response = await client.post(
+            url, params=params, json=payload
+        )
+        response.raise_for_status()
+        data = response.json()
+    return {
+        "external_id": str(
+            data.get("id") or data.get("uid") or uuid4()
+        ),
+        "slot_start": slot_start,
+        "slot_end": slot_end,
+        "status": "confirmed",
+        "demo": False,
+    }

app/services/chat.py

@@ -0,0 +1,215 @@
+"""Core chat orchestration service."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.models import (
+    Conversation,
+    Lead,
+    Message,
+    UnansweredQuestion,
+)
+from app.services import calcom, handoff, leads, llm
+from app.services.language import detect_language
+from app.services.rag import get_knowledge_store
+
+BOOKING_HINTS = (
+    "book",
+    "appointment",
+    "schedule",
+    "meeting",
+    "slot",
+    "rendez-vous",
+    "rdv",
+    "créneau",
+    "запис",
+    "встреч",
+    "слот",
+)
+
+
+GREETINGS = {
+    "en": (
+        "Hello! I am ReplyFlow for Nordic Paper Solutions. "
+        "Ask about products, pricing, delivery, or book a call."
+    ),
+    "fr": (
+        "Bonjour ! Je suis ReplyFlow pour Nordic Paper "
+        "Solutions. Posez vos questions sur les produits, "
+        "tarifs, livraison, ou réservez un appel."
+    ),
+    "ru": (
+        "Здравствуйте! Я ReplyFlow для Nordic Paper "
+        "Solutions. Спросите о продуктах, ценах, доставке "
+        "или запишитесь на звонок."
+    ),
+}
+
+
+async def start_conversation(
+    db: AsyncSession,
+    *,
+    channel: str = "web",
+    ui_language: str = "en",
+    external_id: Optional[str] = None,
+) -> tuple[Conversation, str]:
+    """Create conversation + empty lead + greeting."""
+    lang = ui_language if ui_language in GREETINGS else "en"
+    conv = Conversation(
+        channel=channel,
+        language=lang,
+        external_id=external_id,
+    )
+    db.add(conv)
+    await db.flush()
+    db.add(Lead(conversation_id=conv.id))
+    greeting = GREETINGS[lang]
+    db.add(
+        Message(
+            conversation_id=conv.id,
+            role="assistant",
+            content=greeting,
+            language=lang,
+            grounded=True,
+        )
+    )
+    await db.commit()
+    await db.refresh(conv)
+    return conv, greeting
+
+
+async def handle_user_message(
+    db: AsyncSession,
+    *,
+    conversation_id: int,
+    message: str,
+    ui_language: str = "en",
+) -> dict[str, Any]:
+    """Process one user turn end-to-end."""
+    result = await db.execute(
+        select(Conversation)
+        .where(Conversation.id == conversation_id)
+        .options(
+            selectinload(Conversation.messages),
+            selectinload(Conversation.lead),
+        )
+    )
+    conv = result.scalar_one()
+    language = detect_language(message, default=ui_language)
+    conv.language = language
+
+    previous_bot = None
+    for msg in reversed(conv.messages):
+        if msg.role == "assistant":
+            previous_bot = msg.content
+            break
+
+    lead = conv.lead or Lead(conversation_id=conv.id)
+    if conv.lead is None:
+        db.add(lead)
+        await db.flush()
+    leads.update_lead_from_message(lead, message, previous_bot)
+
+    db.add(
+        Message(
+            conversation_id=conv.id,
+            role="user",
+            content=message,
+            language=language,
+        )
+    )
+
+    wants_booking = any(
+        h in message.lower() for h in BOOKING_HINTS
+    )
+    store = get_knowledge_store()
+    chunks = await store.search(message, top_k=4)
+    grounded = bool(chunks)
+
+    if not grounded:
+        conv.failure_streak += 1
+        db.add(
+            UnansweredQuestion(
+                conversation_id=conv.id,
+                question=message,
+            )
+        )
+    else:
+        conv.failure_streak = 0
+
+    history = [
+        {"role": m.role, "content": m.content}
+        for m in conv.messages
+        if m.role in {"user", "assistant"}
+    ]
+    lead_state = leads.lead_to_dict(lead)
+
+    do_handoff, reason = handoff.should_handoff(
+        message=message,
+        failure_streak=conv.failure_streak,
+        grounded=grounded,
+    )
+
+    suggested_slots = None
+    reply: str
+    if do_handoff:
+        conv.handed_off = True
+        conv.status = "handed_off"
+        reply = handoff.handoff_message(language, reason)
+        await handoff.notify_handoff(
+            conversation_id=conv.id,
+            reason=reason,
+            history=history + [{"role": "user", "content": message}],
+            lead=lead_state,
+        )
+    else:
+        reply, grounded = await llm.generate_reply(
+            question=message,
+            language=language,
+            context_chunks=chunks,
+            history=history,
+            lead_state=lead_state,
+        )
+        if wants_booking or (
+            lead.complete and "book" in reply.lower()
+        ):
+            suggested_slots = await calcom.get_available_slots(3)
+            offer = {
+                "en": "Here are 3 available slots:",
+                "fr": "Voici 3 créneaux disponibles :",
+                "ru": "Вот 3 свободных слота:",
+            }
+            reply += "\n\n" + offer.get(language, offer["en"])
+            for i, slot in enumerate(suggested_slots, start=1):
+                reply += f"\n{i}. {slot['label']}"
+
+        if grounded and not conv.handed_off:
+            conv.resolved_without_human = True
+
+    db.add(
+        Message(
+            conversation_id=conv.id,
+            role="assistant",
+            content=reply,
+            language=language,
+            grounded=grounded if not do_handoff else None,
+        )
+    )
+    conv.updated_at = conv.updated_at
+    await db.commit()
+
+    return {
+        "conversation_id": conv.id,
+        "reply": reply,
+        "language": language,
+        "grounded": grounded and not do_handoff,
+        "lead": leads.lead_to_dict(lead),
+        "suggested_slots": suggested_slots,
+        "handed_off": conv.handed_off,
+        "appointment_booked": conv.appointment_booked,
+    }

app/services/embeddings.py

@@ -0,0 +1,99 @@
+"""Embedding helpers with OpenAI or local fallback."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Sequence
+
+import numpy as np
+
+from app.config import get_settings
+
+_DIM = 384
+
+
+def _tokenize(text: str) -> list[str]:
+    return re.findall(r"[\w\-]+", text.lower(), flags=re.UNICODE)
+
+
+def _local_embed(text: str) -> list[float]:
+    """Deterministic bag-of-tokens embedding for demo mode."""
+    vec = np.zeros(_DIM, dtype=np.float32)
+    tokens = _tokenize(text)
+    if not tokens:
+        return vec.tolist()
+    for token in tokens:
+        digest = hashlib.sha256(token.encode("utf-8")).digest()
+        idx = int.from_bytes(digest[:4], "little") % _DIM
+        sign = 1.0 if digest[4] % 2 == 0 else -1.0
+        vec[idx] += sign
+    norm = float(np.linalg.norm(vec))
+    if norm > 0:
+        vec /= norm
+    return vec.tolist()
+
+
+async def embed_texts(texts: Sequence[str]) -> list[list[float]]:
+    """Embed texts via OpenAI or local fallback."""
+    settings = get_settings()
+    if not settings.has_openai:
+        return [_local_embed(t) for t in texts]
+
+    from openai import AsyncOpenAI
+
+    client = AsyncOpenAI(api_key=settings.openai_api_key)
+    response = await client.embeddings.create(
+        model=settings.openai_embedding_model,
+        input=list(texts),
+    )
+    return [item.embedding for item in response.data]
+
+
+def cosine_similarity(a: Sequence[float], b: Sequence[float]) -> float:
+    """Cosine similarity between two vectors."""
+    va = np.asarray(a, dtype=np.float32)
+    vb = np.asarray(b, dtype=np.float32)
+    denom = float(np.linalg.norm(va) * np.linalg.norm(vb))
+    if denom == 0:
+        return 0.0
+    return float(np.dot(va, vb) / denom)
+
+
+def token_overlap_score(query: str, document: str) -> float:
+    """Simple keyword overlap for offline demo retrieval."""
+    q_tokens = {
+        t for t in _tokenize(query) if len(t) > 2
+    }
+    if not q_tokens:
+        return 0.0
+    d_tokens = set(_tokenize(document))
+    if not d_tokens:
+        return 0.0
+    hits = q_tokens & d_tokens
+    return len(hits) / len(q_tokens)
+
+
+def chunk_text(
+    text: str,
+    chunk_size: int = 700,
+    overlap: int = 120,
+) -> list[str]:
+    """Split text into overlapping chunks."""
+    cleaned = re.sub(r"\s+", " ", text).strip()
+    if not cleaned:
+        return []
+    if len(cleaned) <= chunk_size:
+        return [cleaned]
+
+    chunks: list[str] = []
+    start = 0
+    while start < len(cleaned):
+        end = min(len(cleaned), start + chunk_size)
+        chunk = cleaned[start:end].strip()
+        if chunk:
+            chunks.append(chunk)
+        if end >= len(cleaned):
+            break
+        start = max(0, end - overlap)
+    return chunks

app/services/handoff.py

@@ -0,0 +1,117 @@
+"""Human handoff detection and notification."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+SENSITIVE_HINTS = (
+    "complaint",
+    "réclamation",
+    "reclamation",
+    "litige",
+    "lawsuit",
+    "lawyer",
+    "avocat",
+    "refund",
+    "remboursement",
+    "scam",
+    "fraud",
+    "мошен",
+    "жалоб",
+    "претенз",
+    "возврат",
+    "суд",
+)
+
+HANDOFF_PHRASES = (
+    "human",
+    "agent",
+    "operator",
+    "speak to someone",
+    "real person",
+    "humain",
+    "conseiller",
+    "parler à quelqu'un",
+    "оператор",
+    "человек",
+    "живой",
+    "специалист",
+)
+
+
+def should_handoff(
+    *,
+    message: str,
+    failure_streak: int,
+    grounded: bool,
+) -> tuple[bool, str]:
+    """Decide whether to escalate to a human."""
+    lowered = message.lower()
+    if any(p in lowered for p in HANDOFF_PHRASES):
+        return True, "explicit_request"
+    if any(p in lowered for p in SENSITIVE_HINTS):
+        return True, "sensitive_topic"
+    if not grounded and failure_streak >= 2:
+        return True, "consecutive_failures"
+    return False, ""
+
+
+async def notify_handoff(
+    *,
+    conversation_id: int,
+    reason: str,
+    history: list[dict[str, str]],
+    lead: dict[str, Any],
+) -> None:
+    """Send handoff payload to webhook if configured."""
+    settings = get_settings()
+    payload = {
+        "conversation_id": conversation_id,
+        "reason": reason,
+        "lead": lead,
+        "history": history[-20:],
+        "app": settings.app_name,
+    }
+    if not settings.handoff_webhook_url:
+        logger.info(
+            "Handoff (no webhook): conversation=%s reason=%s",
+            conversation_id,
+            reason,
+        )
+        return
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            await client.post(
+                settings.handoff_webhook_url, json=payload
+            )
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("Handoff webhook failed: %s", exc)
+
+
+def handoff_message(language: str, reason: str) -> str:
+    """User-facing handoff acknowledgement."""
+    messages = {
+        "en": (
+            "I am transferring you to a human teammate. "
+            "They will see this conversation and follow up "
+            f"shortly. (reason: {reason.replace('_', ' ')})"
+        ),
+        "fr": (
+            "Je vous transfère à un conseiller humain. "
+            "Il verra cet échange et vous répondra bientôt. "
+            f"(motif : {reason.replace('_', ' ')})"
+        ),
+        "ru": (
+            "Передаю вас живому специалисту. Он увидит "
+            "этот диалог и скоро свяжется с вами. "
+            f"(причина: {reason.replace('_', ' ')})"
+        ),
+    }
+    return messages.get(language, messages["en"])

app/services/language.py

@@ -0,0 +1,64 @@
+"""Language detection helpers."""
+
+from __future__ import annotations
+
+from langdetect import DetectorFactory, detect
+from langdetect.lang_detect_exception import (
+    LangDetectException,
+)
+
+DetectorFactory.seed = 0
+
+SUPPORTED = {"en", "fr", "ru"}
+
+_FALLBACK_HINTS = {
+    "fr": (
+        "bonjour",
+        "merci",
+        "prix",
+        "rendez-vous",
+        "horaire",
+        "livraison",
+        "devis",
+    ),
+    "ru": (
+        "привет",
+        "спасибо",
+        "цена",
+        "доставка",
+        "запись",
+        "стоимость",
+        "здравствуйте",
+    ),
+}
+
+
+def detect_language(text: str, default: str = "en") -> str:
+    """Detect message language among en/fr/ru."""
+    cleaned = (text or "").strip()
+    if not cleaned:
+        return default
+
+    lowered = cleaned.lower()
+    for lang, hints in _FALLBACK_HINTS.items():
+        if any(h in lowered for h in hints):
+            return lang
+
+    try:
+        code = detect(cleaned)
+    except LangDetectException:
+        return default
+
+    if code.startswith("ru"):
+        return "ru"
+    if code.startswith("fr"):
+        return "fr"
+    if code.startswith("en"):
+        return "en"
+    return default
+
+
+def normalize_ui_language(code: str) -> str:
+    """Clamp UI language to supported codes."""
+    value = (code or "en").lower()[:2]
+    return value if value in SUPPORTED else "en"

app/services/leads.py

@@ -0,0 +1,176 @@
+"""Conversational lead qualification."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from app.models import Lead
+
+EMAIL_RE = re.compile(
+    r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+"
+)
+PHONE_RE = re.compile(r"\+?\d[\d\s\-()]{7,}\d")
+
+BUDGET_HINTS = (
+    "budget",
+    "€",
+    "$",
+    "eur",
+    "usd",
+    "rub",
+    "₽",
+    "тысяч",
+    "euros",
+    "dollars",
+)
+
+NEED_HINTS = (
+    "need",
+    "besoin",
+    "нужн",
+    "want",
+    "looking",
+    "cherche",
+    "ищ",
+    "order",
+    "commande",
+    "заказ",
+)
+
+CONTACT_HINTS = (
+    "email",
+    "mail",
+    "phone",
+    "téléphone",
+    "телефон",
+    "whatsapp",
+    "call",
+    "звон",
+)
+
+
+def lead_to_dict(lead: Optional[Lead]) -> dict[str, Any]:
+    """Serialize lead fields for prompts/UI."""
+    if lead is None:
+        return {
+            "name": None,
+            "need": None,
+            "budget": None,
+            "contact_channel": None,
+            "email": None,
+            "phone": None,
+            "complete": False,
+        }
+    return {
+        "name": lead.name,
+        "need": lead.need,
+        "budget": lead.budget,
+        "contact_channel": lead.contact_channel,
+        "email": lead.email,
+        "phone": lead.phone,
+        "complete": lead.complete,
+    }
+
+
+def update_lead_from_message(
+    lead: Lead,
+    message: str,
+    previous_bot: Optional[str] = None,
+) -> Lead:
+    """Extract lead fields from the latest user message."""
+    text = message.strip()
+    lowered = text.lower()
+    bot = (previous_bot or "").lower()
+
+    email = EMAIL_RE.search(text)
+    if email and not lead.email:
+        lead.email = email.group(0)
+        if not lead.contact_channel:
+            lead.contact_channel = "email"
+
+    phone = PHONE_RE.search(text)
+    if phone and not lead.phone:
+        lead.phone = re.sub(r"\s+", "", phone.group(0))
+        if not lead.contact_channel:
+            lead.contact_channel = "phone"
+
+    if not lead.name and (
+        "name" in bot
+        or "nom" in bot
+        or "зовут" in bot
+        or "зовут" in bot
+        or "call me" in lowered
+        or "je m'appelle" in lowered
+        or "меня зовут" in lowered
+    ):
+        lead.name = _extract_name(text)
+
+    if not lead.name and _looks_like_name(text):
+        lead.name = text.strip()[:80]
+
+    if not lead.budget and (
+        any(h in lowered for h in BUDGET_HINTS)
+        or "budget" in bot
+        or "бюджет" in bot
+    ):
+        lead.budget = text[:64]
+
+    if not lead.need and (
+        any(h in lowered for h in NEED_HINTS)
+        or "need" in bot
+        or "besoin" in bot
+        or "помощь" in bot
+    ):
+        lead.need = text[:500]
+
+    if not lead.contact_channel and (
+        any(h in lowered for h in CONTACT_HINTS)
+        or "reach" in bot
+        or "contacter" in bot
+        or "связаться" in bot
+    ):
+        if "whatsapp" in lowered:
+            lead.contact_channel = "whatsapp"
+        elif "mail" in lowered or "email" in lowered:
+            lead.contact_channel = "email"
+        elif "phone" in lowered or "tél" in lowered or "телефон" in lowered:
+            lead.contact_channel = "phone"
+        else:
+            lead.contact_channel = text[:64]
+
+    lead.complete = all(
+        [
+            lead.name,
+            lead.need,
+            lead.budget,
+            lead.contact_channel,
+        ]
+    )
+    return lead
+
+
+def _looks_like_name(text: str) -> bool:
+    words = text.strip().split()
+    if not (1 <= len(words) <= 3):
+        return False
+    if any(ch.isdigit() for ch in text):
+        return False
+    if len(text) > 40:
+        return False
+    return text[:1].isupper() or all(
+        w[:1].isupper() for w in words if w
+    )
+
+
+def _extract_name(text: str) -> str:
+    patterns = [
+        r"(?:je m'appelle|my name is|i am|i'm|меня зовут)\s+(.+)",
+        r"(?:call me)\s+(.+)",
+    ]
+    lowered = text.strip()
+    for pattern in patterns:
+        match = re.search(pattern, lowered, flags=re.I)
+        if match:
+            return match.group(1).strip(" .,!")[:80]
+    return text.strip()[:80]

app/services/llm.py

@@ -0,0 +1,171 @@
+"""LLM reply generation with grounded RAG answers."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def build_system_prompt(
+    *,
+    business: str,
+    context: str,
+    lead_state: dict[str, Any],
+) -> str:
+    """Build the system prompt in a summary + context form."""
+    system_prompt = (
+        f"You are acting as ReplyFlow, the customer assistant "
+        f"for {business}. You are answering questions on "
+        f"{business}'s website and chat channels, particularly "
+        f"questions related to products, pricing, delivery, "
+        f"returns, and booking a sales call. "
+        f"Your responsibility is to represent {business} as "
+        f"faithfully as possible. "
+        f"You are given knowledge-base excerpts which you must "
+        f"use to answer questions. "
+        f"Be professional and engaging, as if talking to a "
+        f"potential customer. "
+        f"Answer ONLY using the provided Context. Never invent "
+        f"prices, policies, or facts. "
+        f"If you don't know the answer, say so clearly and offer "
+        f"to transfer to a human or book a call. "
+        f"If the user seems ready to buy or book, gently offer "
+        f"an appointment. "
+        f"Reply in English. Be concise and helpful."
+    )
+
+    system_prompt += (
+        f"\n\n## Business:\n{business}\n\n"
+        f"## Context:\n{context}\n\n"
+        f"## Lead profile so far:\n{lead_state}\n\n"
+    )
+
+    system_prompt += (
+        "With this context, please chat with the user, always "
+        f"staying in character as ReplyFlow for {business}."
+    )
+    return system_prompt
+
+
+async def generate_reply(
+    *,
+    question: str,
+    language: str,
+    context_chunks: list[dict[str, Any]],
+    history: list[dict[str, str]],
+    lead_state: dict[str, Any],
+) -> tuple[str, bool]:
+    """
+    Generate a grounded reply.
+
+    Returns (reply_text, grounded).
+    """
+    settings = get_settings()
+    context_text = "\n\n".join(
+        f"[{i + 1}] {c['text']}"
+        for i, c in enumerate(context_chunks)
+    )
+    grounded = bool(context_chunks)
+
+    if not grounded:
+        return _no_context_reply(), False
+
+    if settings.has_openai:
+        try:
+            return await _openai_reply(
+                question=question,
+                context_text=context_text,
+                history=history,
+                lead_state=lead_state,
+            ), True
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("OpenAI failed: %s", exc)
+
+    return _demo_reply(
+        question=question,
+        context_chunks=context_chunks,
+        lead_state=lead_state,
+    ), True
+
+
+async def _openai_reply(
+    *,
+    question: str,
+    context_text: str,
+    history: list[dict[str, str]],
+    lead_state: dict[str, Any],
+) -> str:
+    from openai import AsyncOpenAI
+
+    settings = get_settings()
+    client = AsyncOpenAI(api_key=settings.openai_api_key)
+    system = build_system_prompt(
+        business=settings.demo_business_name,
+        context=context_text,
+        lead_state=lead_state,
+    )
+    messages: list[dict[str, str]] = [
+        {"role": "system", "content": system},
+    ]
+    for item in history[-8:]:
+        messages.append(
+            {"role": item["role"], "content": item["content"]}
+        )
+    messages.append({"role": "user", "content": question})
+
+    response = await client.chat.completions.create(
+        model=settings.openai_model,
+        messages=messages,
+        temperature=0.2,
+        max_tokens=500,
+    )
+    return (response.choices[0].message.content or "").strip()
+
+
+def _no_context_reply() -> str:
+    return (
+        "I do not have that information in our knowledge "
+        "base, so I will not invent an answer. I can "
+        "transfer you to a human or help book a call."
+    )
+
+
+def _demo_reply(
+    *,
+    question: str,
+    context_chunks: list[dict[str, Any]],
+    lead_state: dict[str, Any],
+) -> str:
+    """Template reply for offline / no-key demo mode."""
+    best = context_chunks[0]["text"]
+    excerpt = best[:420].rstrip()
+    if len(best) > 420:
+        excerpt += "…"
+
+    missing = [
+        field
+        for field in ("name", "need", "budget", "contact_channel")
+        if not lead_state.get(field)
+    ]
+
+    followups = {
+        "name": "May I have your name?",
+        "need": "What do you need help with?",
+        "budget": "What budget range are you considering?",
+        "contact_channel": (
+            "How should we reach you (email or phone)?"
+        ),
+    }
+    reply = f"Based on our documentation:\n\n{excerpt}"
+    if missing:
+        reply += f"\n\n{followups[missing[0]]}"
+    else:
+        reply += (
+            "\n\nI can also propose available meeting slots "
+            "if you would like to book a call."
+        )
+    return reply

app/services/rag.py

@@ -0,0 +1,229 @@
+"""RAG knowledge base: ingest, search, no hallucination."""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from pathlib import Path
+from typing import Any
+
+from bs4 import BeautifulSoup
+from pypdf import PdfReader
+
+from app.config import get_settings
+from app.services.embeddings import (
+    chunk_text,
+    cosine_similarity,
+    embed_texts,
+    token_overlap_score,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class KnowledgeStore:
+    """File-backed vector store (Chroma when available)."""
+
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self._collection = None
+        self._fallback_path = (
+            Path(self.settings.chroma_path) / "fallback.json"
+        )
+        self._fallback: list[dict[str, Any]] = []
+        self._init_store()
+
+    def _init_store(self) -> None:
+        path = Path(self.settings.chroma_path)
+        path.mkdir(parents=True, exist_ok=True)
+        try:
+            import chromadb
+
+            client = chromadb.PersistentClient(path=str(path))
+            self._collection = client.get_or_create_collection(
+                name="replyflow_kb",
+                metadata={"hnsw:space": "cosine"},
+            )
+            logger.info("Chroma knowledge store ready")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "Chroma unavailable (%s); using JSON fallback",
+                exc,
+            )
+            self._collection = None
+            self._load_fallback()
+
+    def _load_fallback(self) -> None:
+        if self._fallback_path.exists():
+            self._fallback = json.loads(
+                self._fallback_path.read_text(encoding="utf-8")
+            )
+        else:
+            self._fallback = []
+
+    def _save_fallback(self) -> None:
+        self._fallback_path.parent.mkdir(
+            parents=True, exist_ok=True
+        )
+        self._fallback_path.write_text(
+            json.dumps(self._fallback, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    @property
+    def chunk_count(self) -> int:
+        if self._collection is not None:
+            return int(self._collection.count())
+        return len(self._fallback)
+
+    async def add_chunks(
+        self,
+        chunks: list[str],
+        metadata: dict[str, Any],
+    ) -> int:
+        """Embed and store text chunks."""
+        if not chunks:
+            return 0
+        embeddings = await embed_texts(chunks)
+        ids = [str(uuid.uuid4()) for _ in chunks]
+        metadatas = [
+            {**metadata, "chunk_index": i}
+            for i in range(len(chunks))
+        ]
+
+        if self._collection is not None:
+            self._collection.add(
+                ids=ids,
+                documents=chunks,
+                embeddings=embeddings,
+                metadatas=metadatas,
+            )
+        else:
+            for i, chunk in enumerate(chunks):
+                self._fallback.append(
+                    {
+                        "id": ids[i],
+                        "document": chunk,
+                        "embedding": embeddings[i],
+                        "metadata": metadatas[i],
+                    }
+                )
+            self._save_fallback()
+        return len(chunks)
+
+    async def search(
+        self,
+        query: str,
+        top_k: int = 4,
+        min_score: float = 0.12,
+    ) -> list[dict[str, Any]]:
+        """Return relevant chunks above similarity threshold."""
+        if self.chunk_count == 0:
+            return []
+
+        query_emb = (await embed_texts([query]))[0]
+        use_openai = get_settings().has_openai
+
+        if self._collection is not None:
+            result = self._collection.query(
+                query_embeddings=[query_emb],
+                n_results=min(top_k, max(1, self.chunk_count)),
+            )
+            docs = result.get("documents", [[]])[0]
+            metas = result.get("metadatas", [[]])[0]
+            dists = result.get("distances", [[]])[0]
+            hits: list[dict[str, Any]] = []
+            for doc, meta, dist in zip(docs, metas, dists):
+                vector_score = 1.0 - float(dist)
+                keyword = token_overlap_score(query, doc)
+                score = (
+                    vector_score
+                    if use_openai
+                    else 0.45 * vector_score + 0.55 * keyword
+                )
+                if score >= min_score:
+                    hits.append(
+                        {
+                            "text": doc,
+                            "metadata": meta or {},
+                            "score": score,
+                        }
+                    )
+            hits.sort(key=lambda x: x["score"], reverse=True)
+            return hits[:top_k]
+
+        scored = []
+        for item in self._fallback:
+            vector_score = cosine_similarity(
+                query_emb, item["embedding"]
+            )
+            keyword = token_overlap_score(query, item["document"])
+            score = 0.35 * vector_score + 0.65 * keyword
+            if score >= min_score:
+                scored.append(
+                    {
+                        "text": item["document"],
+                        "metadata": item["metadata"],
+                        "score": score,
+                    }
+                )
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        return scored[:top_k]
+
+
+_store: KnowledgeStore | None = None
+
+
+def get_knowledge_store() -> KnowledgeStore:
+    """Singleton knowledge store."""
+    global _store
+    if _store is None:
+        _store = KnowledgeStore()
+    return _store
+
+
+def extract_text_from_file(path: Path) -> str:
+    """Extract text from pdf, html, md, or txt."""
+    suffix = path.suffix.lower()
+    raw = path.read_bytes()
+    if suffix == ".pdf":
+        reader = PdfReader(str(path))
+        parts = []
+        for page in reader.pages:
+            parts.append(page.extract_text() or "")
+        return "\n".join(parts)
+    text = raw.decode("utf-8", errors="ignore")
+    if suffix in {".html", ".htm"}:
+        soup = BeautifulSoup(text, "html.parser")
+        return soup.get_text(separator="\n")
+    return text
+
+
+async def ingest_path(path: Path, source_type: str) -> int:
+    """Ingest a single file into the knowledge store."""
+    text = extract_text_from_file(path)
+    chunks = chunk_text(text)
+    store = get_knowledge_store()
+    return await store.add_chunks(
+        chunks,
+        {
+            "filename": path.name,
+            "source_type": source_type,
+        },
+    )
+
+
+async def ingest_directory(directory: Path) -> int:
+    """Ingest all supported files from a directory."""
+    total = 0
+    patterns = ("*.md", "*.txt", "*.pdf", "*.html", "*.htm")
+    files: list[Path] = []
+    for pattern in patterns:
+        files.extend(directory.glob(pattern))
+    for path in sorted(set(files)):
+        source = path.suffix.lower().lstrip(".") or "text"
+        count = await ingest_path(path, source)
+        total += count
+        logger.info("Ingested %s (%s chunks)", path.name, count)
+    return total

app/static/chat.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>ReplyFlow Chat</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&family=Syne:wght@600;700;800&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="/static/css/styles.css" />
+</head>
+<body>
+    <div class="shell">
+        <header class="topbar">
+            <a class="brand" href="/">
+                <span class="brand-mark" aria-hidden="true"></span>
+                <span>ReplyFlow</span>
+            </a>
+            <nav class="nav">
+                <a href="/dashboard">Dashboard</a>
+            </nav>
+        </header>
+
+        <div class="chat-layout">
+            <section class="panel chat-panel">
+                <div class="chat-header">
+                    <div>
+                        <h1>ReplyFlow assistant</h1>
+                        <div style="color:var(--muted);font-size:0.9rem">
+                            Ask about products, pricing, delivery, or booking
+                        </div>
+                    </div>
+                    <span class="badge" id="conv-id">—</span>
+                </div>
+                <div class="messages" id="messages" aria-live="polite"></div>
+                <form class="composer" id="composer">
+                    <input
+                        id="message-input"
+                        type="text"
+                        autocomplete="off"
+                        placeholder="Type your message…"
+                        required
+                    />
+                    <button class="btn btn-primary" type="submit">Send</button>
+                </form>
+            </section>
+
+            <aside class="side-stack">
+                <div class="panel side-card">
+                    <h2>Lead profile</h2>
+                    <div class="kv" id="lead-box">
+                        <div><span>Name</span><span id="lead-name">—</span></div>
+                        <div><span>Need</span><span id="lead-need">—</span></div>
+                        <div><span>Budget</span><span id="lead-budget">—</span></div>
+                        <div><span>Contact</span><span id="lead-contact">—</span></div>
+                    </div>
+                </div>
+                <div class="panel side-card">
+                    <h2>Suggested slots</h2>
+                    <div class="slots" id="slots-box">
+                        <div style="color:var(--muted);font-size:0.9rem">—</div>
+                    </div>
+                </div>
+                <div class="panel side-card">
+                    <h2>Integrations</h2>
+                    <div class="kv" id="health-box">
+                        <div><span>OpenAI</span><span id="h-openai">…</span></div>
+                        <div><span>Cal.com</span><span id="h-calcom">…</span></div>
+                        <div><span>WhatsApp</span><span id="h-whatsapp">…</span></div>
+                        <div><span>KB chunks</span><span id="h-chunks">…</span></div>
+                    </div>
+                </div>
+            </aside>
+        </div>
+    </div>
+
+    <script src="/static/js/chat.js"></script>
+</body>
+</html>

app/static/css/styles.css

@@ -0,0 +1,483 @@
+/* ReplyFlow design system */
+:root {
+    --bg0: #0f1c1a;
+    --bg1: #16302b;
+    --bg2: #1e3d36;
+    --ink: #f3f0e8;
+    --muted: #b7c4bf;
+    --line: rgba(243, 240, 232, 0.12);
+    --accent: #d4a24c;
+    --accent-2: #7ec8b4;
+    --danger: #e07a5f;
+    --ok: #7ec8b4;
+    --card: rgba(22, 48, 43, 0.72);
+    --shadow: 0 24px 60px rgba(0, 0, 0, 0.35);
+    --radius: 18px;
+    --font-display: "Syne", sans-serif;
+    --font-body: "Manrope", sans-serif;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+    min-height: 100%;
+}
+
+body {
+    font-family: var(--font-body);
+    color: var(--ink);
+    background:
+        radial-gradient(1200px 700px at 10% -10%, #2a5a4e 0%, transparent 55%),
+        radial-gradient(900px 600px at 100% 0%, #3a2f18 0%, transparent 50%),
+        linear-gradient(160deg, var(--bg0), #122421 45%, #0c1614);
+    background-attachment: fixed;
+}
+
+a {
+    color: var(--accent-2);
+    text-decoration: none;
+}
+
+a:hover {
+    color: var(--accent);
+}
+
+.shell {
+    width: min(1120px, calc(100% - 2rem));
+    margin: 0 auto;
+}
+
+.topbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    padding: 1.25rem 0;
+}
+
+.brand {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    font-family: var(--font-display);
+    font-weight: 700;
+    letter-spacing: -0.03em;
+    font-size: 1.35rem;
+    color: var(--ink);
+}
+
+.brand-mark {
+    width: 2rem;
+    height: 2rem;
+    border-radius: 0.55rem;
+    background:
+        linear-gradient(135deg, var(--accent), #f0d29a),
+        var(--accent);
+    box-shadow: 0 0 0 4px rgba(212, 162, 76, 0.15);
+    animation: pulse-mark 3.2s ease-in-out infinite;
+}
+
+@keyframes pulse-mark {
+    0%,
+    100% {
+        transform: scale(1);
+    }
+    50% {
+        transform: scale(1.06);
+    }
+}
+
+.nav {
+    display: flex;
+    align-items: center;
+    gap: 0.85rem;
+    flex-wrap: wrap;
+}
+
+.nav a {
+    color: var(--muted);
+    font-size: 0.95rem;
+}
+
+.hero {
+    min-height: calc(100vh - 5.5rem);
+    display: grid;
+    align-items: end;
+    padding: 2rem 0 4rem;
+    position: relative;
+    overflow: hidden;
+}
+
+.hero-copy {
+    max-width: 38rem;
+    position: relative;
+    z-index: 2;
+    animation: rise 0.9s ease both;
+}
+
+@keyframes rise {
+    from {
+        opacity: 0;
+        transform: translateY(18px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+.hero h1 {
+    font-family: var(--font-display);
+    font-size: clamp(2.8rem, 7vw, 5.2rem);
+    line-height: 0.95;
+    letter-spacing: -0.045em;
+    margin: 0 0 1rem;
+}
+
+.hero p {
+    color: var(--muted);
+    font-size: 1.1rem;
+    line-height: 1.55;
+    margin: 0 0 1.6rem;
+    max-width: 32rem;
+}
+
+.cta-row {
+    display: flex;
+    gap: 0.75rem;
+    flex-wrap: wrap;
+}
+
+.btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.4rem;
+    border: 0;
+    border-radius: 999px;
+    padding: 0.85rem 1.25rem;
+    font: inherit;
+    font-weight: 600;
+    cursor: pointer;
+    transition: transform 0.2s ease, background 0.2s ease;
+}
+
+.btn:hover {
+    transform: translateY(-1px);
+}
+
+.btn-primary {
+    background: linear-gradient(135deg, var(--accent), #e8c078);
+    color: #1a1408;
+}
+
+.btn-ghost {
+    background: transparent;
+    color: var(--ink);
+    border: 1px solid var(--line);
+}
+
+.hero-visual {
+    position: absolute;
+    inset: 8% 0 auto auto;
+    width: min(48vw, 520px);
+    height: min(62vh, 560px);
+    border-radius: 28% 48% 36% 54% / 42% 30% 55% 40%;
+    background:
+        linear-gradient(145deg, rgba(126, 200, 180, 0.35), transparent 55%),
+        linear-gradient(320deg, rgba(212, 162, 76, 0.4), transparent 50%),
+        #214940;
+    filter: blur(0.2px);
+    animation: morph 12s ease-in-out infinite;
+    z-index: 1;
+}
+
+@keyframes morph {
+    0%,
+    100% {
+        border-radius: 28% 48% 36% 54% / 42% 30% 55% 40%;
+        transform: translateY(0) rotate(0deg);
+    }
+    50% {
+        border-radius: 48% 28% 54% 36% / 30% 48% 36% 52%;
+        transform: translateY(12px) rotate(4deg);
+    }
+}
+
+.section {
+    padding: 3.5rem 0;
+    border-top: 1px solid var(--line);
+}
+
+.section h2 {
+    font-family: var(--font-display);
+    font-size: clamp(1.8rem, 3vw, 2.4rem);
+    letter-spacing: -0.03em;
+    margin: 0 0 0.6rem;
+}
+
+.section > p {
+    color: var(--muted);
+    margin: 0 0 1.5rem;
+    max-width: 40rem;
+}
+
+.feature-list {
+    display: grid;
+    gap: 1rem;
+    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+}
+
+.feature {
+    padding: 1.1rem 0;
+    border-top: 1px solid var(--line);
+}
+
+.feature h3 {
+    margin: 0 0 0.35rem;
+    font-size: 1.05rem;
+}
+
+.feature p {
+    margin: 0;
+    color: var(--muted);
+    line-height: 1.5;
+    font-size: 0.95rem;
+}
+
+.panel {
+    background: var(--card);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow);
+    backdrop-filter: blur(10px);
+}
+
+.chat-layout {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1rem;
+    padding: 1rem 0 2rem;
+}
+
+@media (min-width: 900px) {
+    .chat-layout {
+        grid-template-columns: 1.5fr 0.9fr;
+        align-items: start;
+    }
+}
+
+.chat-panel {
+    display: flex;
+    flex-direction: column;
+    min-height: 70vh;
+}
+
+.chat-header {
+    padding: 1rem 1.1rem;
+    border-bottom: 1px solid var(--line);
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    align-items: center;
+}
+
+.chat-header h1 {
+    margin: 0;
+    font-family: var(--font-display);
+    font-size: 1.35rem;
+}
+
+.messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 1rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+}
+
+.bubble {
+    max-width: 85%;
+    padding: 0.85rem 1rem;
+    border-radius: 1rem;
+    line-height: 1.45;
+    white-space: pre-wrap;
+    animation: rise 0.35s ease both;
+}
+
+.bubble.user {
+    align-self: flex-end;
+    background: rgba(212, 162, 76, 0.22);
+    border: 1px solid rgba(212, 162, 76, 0.35);
+}
+
+.bubble.assistant {
+    align-self: flex-start;
+    background: rgba(255, 255, 255, 0.05);
+    border: 1px solid var(--line);
+}
+
+.composer {
+    display: flex;
+    gap: 0.6rem;
+    padding: 0.9rem;
+    border-top: 1px solid var(--line);
+}
+
+.composer input {
+    flex: 1;
+    border: 1px solid var(--line);
+    background: rgba(0, 0, 0, 0.25);
+    color: var(--ink);
+    border-radius: 999px;
+    padding: 0.85rem 1rem;
+    font: inherit;
+}
+
+.composer input:focus {
+    outline: 1px solid rgba(212, 162, 76, 0.55);
+}
+
+.side-stack {
+    display: grid;
+    gap: 1rem;
+}
+
+.side-card {
+    padding: 1rem 1.1rem;
+}
+
+.side-card h2 {
+    margin: 0 0 0.75rem;
+    font-size: 1rem;
+    font-family: var(--font-display);
+}
+
+.kv {
+    display: grid;
+    gap: 0.45rem;
+    font-size: 0.92rem;
+}
+
+.kv div {
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    border-bottom: 1px dashed var(--line);
+    padding-bottom: 0.35rem;
+}
+
+.kv span:last-child {
+    color: var(--muted);
+    text-align: right;
+}
+
+.slots {
+    display: grid;
+    gap: 0.5rem;
+}
+
+.slot-btn {
+    text-align: left;
+    border: 1px solid var(--line);
+    background: rgba(0, 0, 0, 0.2);
+    color: var(--ink);
+    border-radius: 12px;
+    padding: 0.7rem 0.8rem;
+    cursor: pointer;
+    font: inherit;
+}
+
+.slot-btn:hover {
+    border-color: rgba(126, 200, 180, 0.6);
+}
+
+.stats-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+    gap: 0.85rem;
+    margin: 1rem 0 1.5rem;
+}
+
+.stat {
+    padding: 1rem;
+}
+
+.stat .label {
+    color: var(--muted);
+    font-size: 0.85rem;
+}
+
+.stat .value {
+    font-family: var(--font-display);
+    font-size: 1.8rem;
+    margin-top: 0.25rem;
+}
+
+.table-wrap {
+    overflow-x: auto;
+}
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.92rem;
+}
+
+th,
+td {
+    text-align: left;
+    padding: 0.7rem 0.55rem;
+    border-bottom: 1px solid var(--line);
+    vertical-align: top;
+}
+
+th {
+    color: var(--muted);
+    font-weight: 600;
+}
+
+.badge {
+    display: inline-block;
+    padding: 0.15rem 0.5rem;
+    border-radius: 999px;
+    border: 1px solid var(--line);
+    font-size: 0.75rem;
+    color: var(--muted);
+}
+
+.badge.ok {
+    color: var(--ok);
+    border-color: rgba(126, 200, 180, 0.4);
+}
+
+.badge.warn {
+    color: var(--danger);
+    border-color: rgba(224, 122, 95, 0.45);
+}
+
+.footer {
+    padding: 2rem 0 3rem;
+    color: var(--muted);
+    font-size: 0.9rem;
+    border-top: 1px solid var(--line);
+}
+
+@media (max-width: 720px) {
+    .hero-visual {
+        opacity: 0.35;
+        width: 70vw;
+        height: 40vh;
+    }
+
+    .topbar {
+        flex-direction: column;
+        align-items: flex-start;
+    }
+}

app/static/dashboard.html

@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>ReplyFlow Dashboard</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&family=Syne:wght@600;700;800&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="/static/css/styles.css" />
+</head>
+<body>
+    <div class="shell">
+        <header class="topbar">
+            <a class="brand" href="/">
+                <span class="brand-mark" aria-hidden="true"></span>
+                <span>ReplyFlow</span>
+            </a>
+            <nav class="nav">
+                <a href="/chat">Live demo</a>
+            </nav>
+        </header>
+
+        <section style="padding:1rem 0 2.5rem">
+            <h1 style="font-family:var(--font-display);letter-spacing:-0.03em;margin:0 0 0.4rem">
+                Operator dashboard
+            </h1>
+            <p style="color:var(--muted);margin:0 0 1rem">
+                Conversation metrics and unanswered questions.
+            </p>
+
+            <div class="stats-grid" id="stats-grid">
+                <div class="panel stat"><div class="label">Conversations</div><div class="value" id="s-total">0</div></div>
+                <div class="panel stat"><div class="label">Resolved without human</div><div class="value" id="s-rate">0%</div></div>
+                <div class="panel stat"><div class="label">Appointments</div><div class="value" id="s-appt">0</div></div>
+                <div class="panel stat"><div class="label">Handed off</div><div class="value" id="s-hand">0</div></div>
+                <div class="panel stat"><div class="label">Unanswered</div><div class="value" id="s-unans">0</div></div>
+                <div class="panel stat"><div class="label">Complete leads</div><div class="value" id="s-leads">0</div></div>
+            </div>
+
+            <div class="panel" style="padding:1rem;margin-bottom:1rem">
+                <h2 style="font-family:var(--font-display);font-size:1.1rem;margin:0 0 0.8rem">
+                    Recent conversations
+                </h2>
+                <div class="table-wrap">
+                    <table>
+                        <thead>
+                            <tr>
+                                <th>ID</th>
+                                <th>Channel</th>
+                                <th>Lang</th>
+                                <th>Lead</th>
+                                <th>Status</th>
+                                <th>Msgs</th>
+                                <th>When</th>
+                                <th></th>
+                            </tr>
+                        </thead>
+                        <tbody id="conv-body"></tbody>
+                    </table>
+                </div>
+            </div>
+
+            <div class="panel" style="padding:1rem">
+                <h2 style="font-family:var(--font-display);font-size:1.1rem;margin:0 0 0.8rem">
+                    Recent unanswered
+                </h2>
+                <div class="table-wrap">
+                    <table>
+                        <thead>
+                            <tr>
+                                <th>ID</th>
+                                <th>Conversation</th>
+                                <th>Question</th>
+                                <th>When</th>
+                            </tr>
+                        </thead>
+                        <tbody id="unans-body"></tbody>
+                    </table>
+                </div>
+            </div>
+        </section>
+    </div>
+
+    <script src="/static/js/dashboard.js"></script>
+</body>
+</html>

app/static/index.html

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>ReplyFlow</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&family=Syne:wght@600;700;800&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="/static/css/styles.css" />
+</head>
+<body>
+    <div class="shell">
+        <header class="topbar">
+            <a class="brand" href="/">
+                <span class="brand-mark" aria-hidden="true"></span>
+                <span>ReplyFlow</span>
+            </a>
+            <nav class="nav">
+                <a href="/chat">Live demo</a>
+                <a href="/dashboard">Dashboard</a>
+            </nav>
+        </header>
+
+        <section class="hero">
+            <div class="hero-visual" aria-hidden="true"></div>
+            <div class="hero-copy">
+                <h1>ReplyFlow</h1>
+                <p>
+                    Web and WhatsApp chatbot for SMEs — with booking,
+                    lead capture, and human handoff.
+                </p>
+                <div class="cta-row">
+                    <a class="btn btn-primary" href="/chat">Open chat demo</a>
+                    <a class="btn btn-ghost" href="/dashboard">View dashboard</a>
+                </div>
+            </div>
+        </section>
+
+        <section class="section">
+            <h2>What it does</h2>
+            <p>Built for portfolio demos and real SME deployments.</p>
+            <div class="feature-list">
+                <article class="feature">
+                    <h3>Grounded RAG answers</h3>
+                    <p>Replies only from your docs. If the answer is missing, it says so.</p>
+                </article>
+                <article class="feature">
+                    <h3>Lead qualification</h3>
+                    <p>Collects name, need, budget, and contact channel in conversation.</p>
+                </article>
+                <article class="feature">
+                    <h3>Appointments 24/7</h3>
+                    <p>Suggests three slots and books via Cal.com when keys are set.</p>
+                </article>
+                <article class="feature">
+                    <h3>Human handoff</h3>
+                    <p>Escalates after failures, explicit requests, or sensitive topics.</p>
+                </article>
+            </div>
+        </section>
+
+        <footer class="footer">
+            ReplyFlow · FastAPI · Docker
+        </footer>
+    </div>
+    <script src="/widget.js" defer></script>
+</body>
+</html>

app/static/js/chat.js

@@ -0,0 +1,136 @@
+(() => {
+    const messagesEl = document.getElementById("messages");
+    const composer = document.getElementById("composer");
+    const input = document.getElementById("message-input");
+    const convIdEl = document.getElementById("conv-id");
+    const slotsBox = document.getElementById("slots-box");
+
+    let conversationId = null;
+    let busy = false;
+
+    function addBubble(role, text) {
+        const div = document.createElement("div");
+        div.className = `bubble ${role}`;
+        div.textContent = text;
+        messagesEl.appendChild(div);
+        messagesEl.scrollTop = messagesEl.scrollHeight;
+    }
+
+    function renderLead(lead) {
+        document.getElementById("lead-name").textContent =
+            (lead && lead.name) || "—";
+        document.getElementById("lead-need").textContent =
+            (lead && lead.need) || "—";
+        document.getElementById("lead-budget").textContent =
+            (lead && lead.budget) || "—";
+        document.getElementById("lead-contact").textContent =
+            (lead && (lead.contact_channel || lead.email || lead.phone)) ||
+            "—";
+    }
+
+    function renderSlots(slots) {
+        slotsBox.innerHTML = "";
+        if (!slots || !slots.length) {
+            slotsBox.innerHTML =
+                '<div style="color:var(--muted);font-size:0.9rem">—</div>';
+            return;
+        }
+        slots.forEach((slot) => {
+            const btn = document.createElement("button");
+            btn.type = "button";
+            btn.className = "slot-btn";
+            btn.textContent = slot.label || slot.start;
+            btn.addEventListener("click", () => bookSlot(slot));
+            slotsBox.appendChild(btn);
+        });
+    }
+
+    async function bookSlot(slot) {
+        if (!conversationId) return;
+        const res = await fetch("/api/appointments/book", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                conversation_id: conversationId,
+                slot_start: slot.start,
+                slot_end: slot.end,
+            }),
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            addBubble("assistant", data.detail || "Booking failed");
+            return;
+        }
+        addBubble(
+            "assistant",
+            data.message || "Appointment booked"
+        );
+        renderSlots([]);
+    }
+
+    async function loadHealth() {
+        try {
+            const res = await fetch("/api/health");
+            const data = await res.json();
+            document.getElementById("h-openai").textContent = data.openai
+                ? "on"
+                : "demo";
+            document.getElementById("h-calcom").textContent = data.calcom
+                ? "on"
+                : "demo";
+            document.getElementById("h-whatsapp").textContent = data.whatsapp
+                ? "on"
+                : "demo";
+            document.getElementById("h-chunks").textContent =
+                data.knowledge_chunks;
+        } catch (_) {
+            /* ignore */
+        }
+    }
+
+    async function startChat() {
+        messagesEl.innerHTML = "";
+        const res = await fetch(
+            "/api/chat/start?ui_language=en",
+            { method: "POST" }
+        );
+        const data = await res.json();
+        conversationId = data.conversation_id;
+        convIdEl.textContent = `#${conversationId}`;
+        addBubble("assistant", data.greeting);
+        renderLead(null);
+        renderSlots([]);
+    }
+
+    composer.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        if (busy || !conversationId) return;
+        const text = input.value.trim();
+        if (!text) return;
+        input.value = "";
+        addBubble("user", text);
+        busy = true;
+        try {
+            const res = await fetch("/api/chat/message", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    conversation_id: conversationId,
+                    message: text,
+                    ui_language: "en",
+                }),
+            });
+            const data = await res.json();
+            addBubble("assistant", data.reply);
+            renderLead(data.lead);
+            renderSlots(data.suggested_slots);
+        } catch (err) {
+            addBubble("assistant", "Network error. Please retry.");
+        } finally {
+            busy = false;
+        }
+    });
+
+    loadHealth();
+    startChat();
+})();

app/static/js/dashboard.js

@@ -0,0 +1,78 @@
+(() => {
+    async function loadStats() {
+        const res = await fetch("/api/dashboard/stats");
+        const data = await res.json();
+        document.getElementById("s-total").textContent =
+            data.total_conversations;
+        document.getElementById("s-rate").textContent =
+            `${data.resolution_rate}%`;
+        document.getElementById("s-appt").textContent =
+            data.appointments_booked;
+        document.getElementById("s-hand").textContent = data.handed_off;
+        document.getElementById("s-unans").textContent =
+            data.unanswered_count;
+        document.getElementById("s-leads").textContent =
+            data.leads_complete;
+
+        const unansBody = document.getElementById("unans-body");
+        unansBody.innerHTML = "";
+        (data.recent_unanswered || []).forEach((q) => {
+            const tr = document.createElement("tr");
+            tr.innerHTML = `
+                <td>${q.id}</td>
+                <td>#${q.conversation_id}</td>
+                <td>${escapeHtml(q.question)}</td>
+                <td>${formatWhen(q.created_at)}</td>
+            `;
+            unansBody.appendChild(tr);
+        });
+    }
+
+    async function loadConversations() {
+        const res = await fetch("/api/conversations");
+        const rows = await res.json();
+        const body = document.getElementById("conv-body");
+        body.innerHTML = "";
+        rows.forEach((c) => {
+            const status = c.handed_off
+                ? '<span class="badge warn">handoff</span>'
+                : c.appointment_booked
+                  ? '<span class="badge ok">booked</span>'
+                  : `<span class="badge">${c.status}</span>`;
+            const tr = document.createElement("tr");
+            tr.innerHTML = `
+                <td>#${c.id}</td>
+                <td>${c.channel}</td>
+                <td>${c.language}</td>
+                <td>${escapeHtml(c.lead_name || "—")}</td>
+                <td>${status}</td>
+                <td>${c.message_count}</td>
+                <td>${formatWhen(c.created_at)}</td>
+                <td>
+                    <a href="/api/conversations/${c.id}" target="_blank" rel="noopener">Open</a>
+                    ·
+                    <a href="/api/conversations/${c.id}/export">Export CSV</a>
+                </td>
+            `;
+            body.appendChild(tr);
+        });
+    }
+
+    function formatWhen(value) {
+        try {
+            return new Date(value).toLocaleString();
+        } catch (_) {
+            return value;
+        }
+    }
+
+    function escapeHtml(text) {
+        return String(text)
+            .replaceAll("&", "&amp;")
+            .replaceAll("<", "&lt;")
+            .replaceAll(">", "&gt;");
+    }
+
+    loadStats();
+    loadConversations();
+})();

app/static/widget/replyflow-widget.js

@@ -0,0 +1,115 @@
+/**
+ * ReplyFlow embeddable widget.
+ * Usage: <script src="https://YOUR_HOST/widget.js" defer></script>
+ */
+(function () {
+    if (window.__ReplyFlowWidgetLoaded) return;
+    window.__ReplyFlowWidgetLoaded = true;
+
+    const script =
+        document.currentScript ||
+        document.querySelector('script[src*="widget.js"]');
+    const base =
+        (script && script.src
+            ? script.src.replace(/\/widget\.js(?:\?.*)?$/, "")
+            : window.location.origin) || "";
+
+    const style = document.createElement("style");
+    style.textContent = `
+    #rf-launcher{position:fixed;right:20px;bottom:20px;z-index:99999;
+      width:58px;height:58px;border-radius:50%;border:0;cursor:pointer;
+      background:linear-gradient(135deg,#d4a24c,#e8c078);color:#1a1408;
+      font:700 14px/1 Manrope,system-ui,sans-serif;box-shadow:0 12px 30px rgba(0,0,0,.35)}
+    #rf-panel{position:fixed;right:20px;bottom:90px;z-index:99999;width:min(360px,calc(100vw - 24px));
+      height:min(520px,70vh);display:none;flex-direction:column;overflow:hidden;
+      border-radius:18px;background:#16302b;color:#f3f0e8;border:1px solid rgba(243,240,232,.12);
+      box-shadow:0 24px 60px rgba(0,0,0,.4);font:14px/1.4 Manrope,system-ui,sans-serif}
+    #rf-panel.open{display:flex}
+    #rf-head{padding:12px 14px;border-bottom:1px solid rgba(243,240,232,.12)}
+    #rf-head strong{font-family:Syne,Manrope,sans-serif;letter-spacing:-.02em}
+    #rf-msgs{flex:1;overflow:auto;padding:12px;display:flex;flex-direction:column;gap:8px}
+    .rf-b{max-width:88%;padding:8px 10px;border-radius:12px;white-space:pre-wrap}
+    .rf-u{align-self:flex-end;background:rgba(212,162,76,.22)}
+    .rf-a{align-self:flex-start;background:rgba(255,255,255,.06);border:1px solid rgba(243,240,232,.1)}
+    #rf-form{display:flex;gap:6px;padding:10px;border-top:1px solid rgba(243,240,232,.12)}
+    #rf-form input{flex:1;border-radius:999px;border:1px solid rgba(243,240,232,.15);
+      background:rgba(0,0,0,.25);color:#f3f0e8;padding:10px 12px;font:inherit}
+    #rf-form button{border:0;border-radius:999px;padding:10px 12px;cursor:pointer;
+      background:linear-gradient(135deg,#d4a24c,#e8c078);color:#1a1408;font-weight:700}
+    `;
+    document.head.appendChild(style);
+
+    const launcher = document.createElement("button");
+    launcher.id = "rf-launcher";
+    launcher.type = "button";
+    launcher.setAttribute("aria-label", "Open ReplyFlow chat");
+    launcher.textContent = "RF";
+
+    const panel = document.createElement("div");
+    panel.id = "rf-panel";
+    panel.innerHTML = `
+      <div id="rf-head">
+        <strong>ReplyFlow</strong>
+      </div>
+      <div id="rf-msgs"></div>
+      <form id="rf-form">
+        <input id="rf-input" placeholder="Message…" autocomplete="off" />
+        <button type="submit">Send</button>
+      </form>
+    `;
+
+    document.body.appendChild(panel);
+    document.body.appendChild(launcher);
+
+    const msgs = panel.querySelector("#rf-msgs");
+    const form = panel.querySelector("#rf-form");
+    const input = panel.querySelector("#rf-input");
+    let conversationId = null;
+    let started = false;
+
+    function bubble(role, text) {
+        const el = document.createElement("div");
+        el.className = `rf-b ${role === "user" ? "rf-u" : "rf-a"}`;
+        el.textContent = text;
+        msgs.appendChild(el);
+        msgs.scrollTop = msgs.scrollHeight;
+    }
+
+    async function start() {
+        msgs.innerHTML = "";
+        const res = await fetch(
+            `${base}/api/chat/start?ui_language=en`,
+            { method: "POST" }
+        );
+        const data = await res.json();
+        conversationId = data.conversation_id;
+        bubble("assistant", data.greeting);
+        started = true;
+    }
+
+    launcher.addEventListener("click", async () => {
+        panel.classList.toggle("open");
+        if (panel.classList.contains("open") && !started) {
+            await start();
+        }
+    });
+
+    form.addEventListener("submit", async (e) => {
+        e.preventDefault();
+        const text = input.value.trim();
+        if (!text || !conversationId) return;
+        input.value = "";
+        bubble("user", text);
+        const res = await fetch(`${base}/api/chat/message`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                conversation_id: conversationId,
+                message: text,
+                ui_language: "en",
+            }),
+        });
+        const data = await res.json();
+        bubble("assistant", data.reply || "…");
+    });
+})();

data/chroma/.gitkeep

@@ -0,0 +1 @@
+

data/db/.gitkeep

@@ -0,0 +1 @@
+

data/knowledge/faq_en.md

@@ -0,0 +1,34 @@
+# Nordic Paper Solutions — Product FAQ (English)
+
+## Company
+Nordic Paper Solutions supplies recycled office paper, packaging
+board, and specialty print stock to SMEs across Europe and the
+CIS region. Support languages: English, French, Russian.
+
+## Products
+- OfficeLine A4 80g: box of 5 reams, bright white, FSC recycled.
+- PackShield corrugated board: single and double wall sheets.
+- PrintPro gloss 150g: short-run marketing print stock.
+
+## Pricing (list, excl. VAT)
+- OfficeLine A4 80g: EUR 28 per box (5 × 500 sheets).
+- PackShield single wall: EUR 1.10 per m² (min. 200 m²).
+- PackShield double wall: EUR 1.75 per m² (min. 200 m²).
+- PrintPro gloss 150g: EUR 42 per ream (500 sheets).
+Volume discount: 8% from 20 boxes / 1000 m² in one order.
+
+## Delivery
+- France & Benelux: 2–4 business days.
+- Germany, Poland, Baltics: 3–6 business days.
+- Russia / CIS partners: 7–14 business days via bonded freight.
+Express option (+EUR 45): next-business-day in France only.
+Free shipping above EUR 350 order value (mainland EU).
+
+## Returns
+Unused sealed boxes can be returned within 14 days.
+Opened reams are non-returnable. Custom cut sizes are final sale.
+
+## Hours & booking
+Sales desk: Monday–Friday 09:00–18:00 Europe/Paris.
+ReplyFlow handles FAQs 24/7 and can book a 30-minute call.
+Human transfer is available for complaints and complex quotes.

data/knowledge/faq_fr.md

@@ -0,0 +1,34 @@
+# Nordic Paper Solutions — FAQ produits (Français)
+
+## Entreprise
+Nordic Paper Solutions fournit du papier de bureau recyclé,
+du carton d'emballage et des supports d'impression aux PME
+en Europe et dans la zone CEI. Langues : anglais, français, russe.
+
+## Produits
+- OfficeLine A4 80g : carton de 5 rames, blanc brillant, FSC recyclé.
+- PackShield carton ondulé : simple et double cannelure.
+- PrintPro gloss 150g : papier marketing pour petits tirages.
+
+## Tarifs (HT)
+- OfficeLine A4 80g : 28 EUR le carton (5 × 500 feuilles).
+- PackShield simple : 1,10 EUR / m² (min. 200 m²).
+- PackShield double : 1,75 EUR / m² (min. 200 m²).
+- PrintPro gloss 150g : 42 EUR la rame (500 feuilles).
+Remise volume : 8 % dès 20 cartons / 1000 m² sur une commande.
+
+## Livraison
+- France & Benelux : 2–4 jours ouvrés.
+- Allemagne, Pologne, pays baltes : 3–6 jours ouvrés.
+- Russie / partenaires CEI : 7–14 jours ouvrés.
+Express (+45 EUR) : lendemain ouvré en France uniquement.
+Livraison offerte dès 350 EUR HT (UE continentale).
+
+## Retours
+Cartons scellés non ouverts : retour sous 14 jours.
+Rames ouvertes non reprises. Formats sur mesure non repris.
+
+## Horaires et rendez-vous
+Bureau commercial : lundi–vendredi 09:00–18:00 Europe/Paris.
+ReplyFlow répond 24/7 et peut réserver un appel de 30 minutes.
+Transfert humain pour réclamations et devis complexes.

data/knowledge/faq_ru.md

@@ -0,0 +1,34 @@
+# Nordic Paper Solutions — FAQ (Русский)
+
+## Компания
+Nordic Paper Solutions поставляет переработанную офисную
+бумагу, упаковочный картон и материалы для печати малому
+и среднему бизнесу в Европе и СНГ. Языки: EN, FR, RU.
+
+## Продукты
+- OfficeLine A4 80 г: коробка из 5 пачек, белая, FSC recycled.
+- PackShield гофрокартон: одно- и двухслойные листы.
+- PrintPro gloss 150 г: бумага для коротких маркетинговых тиражей.
+
+## Цены (без НДС)
+- OfficeLine A4 80 г: 28 EUR за коробку (5 × 500 листов).
+- PackShield однослойный: 1,10 EUR / м² (мин. 200 м²).
+- PackShield двухслойный: 1,75 EUR / м² (мин. 200 м²).
+- PrintPro gloss 150 г: 42 EUR за пачку (500 листов).
+Скидка за объём: 8% от 20 коробок / 1000 м² в одном заказе.
+
+## Доставка
+- Франция и Бенилюкс: 2–4 рабочих дня.
+- Германия, Польша, Прибалтика: 3–6 рабочих дней.
+- Россия / партнёры СНГ: 7–14 рабочих дней.
+Экспресс (+45 EUR): на следующий рабочий день только по Франции.
+Бесплатная доставка от 350 EUR (континентальный ЕС).
+
+## Возврат
+Нераспечатанные коробки — возврат в течение 14 дней.
+Открытые пачки не принимаются. Нестандартный рез — без возврата.
+
+## Часы работы и запись
+Отдел продаж: пн–пт 09:00–18:00 Europe/Paris.
+ReplyFlow отвечает 24/7 и может записать на звонок 30 минут.
+Перевод на человека — для жалоб и сложных коммерческих запросов.

data/knowledge/product_page.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Nordic Paper Solutions — Products</title>
+</head>
+<body>
+  <h1>Nordic Paper Solutions</h1>
+  <p>
+    We sell recycled office paper, packaging board, and print stock
+    to SMEs. Languages supported: English, French, Russian.
+  </p>
+  <h2>OfficeLine A4 80g</h2>
+  <p>Box of 5 reams, EUR 28 excl. VAT. FSC recycled bright white.</p>
+  <h2>PackShield board</h2>
+  <p>
+    Single wall EUR 1.10/m², double wall EUR 1.75/m², minimum 200 m².
+  </p>
+  <h2>Delivery promise</h2>
+  <p>
+    France 2–4 days, Germany/Poland/Baltics 3–6 days,
+    CIS partners 7–14 days. Free shipping above EUR 350 in mainland EU.
+  </p>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,14 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.34.0
+sqlalchemy>=2.0.36
+aiosqlite>=0.20.0
+pydantic>=2.10.0
+pydantic-settings>=2.7.0
+httpx>=0.28.0
+python-multipart>=0.0.20
+openai>=1.58.0
+langdetect>=1.0.9
+pypdf>=5.1.0
+beautifulsoup4>=4.12.3
+python-dotenv>=1.0.1
+numpy>=2.1.0

test/test_questions.py

@@ -0,0 +1,108 @@
+"""Test ReplyFlow with a fixed set of smoke questions."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+import httpx
+
+QUESTIONS = [
+    ("en", "How much is OfficeLine A4 80g?"),
+    ("en", "What is the delivery time to France?"),
+    ("en", "Do you offer volume discounts?"),
+    ("en", "What is your return policy?"),
+    ("en", "Can I book a sales call?"),
+    ("fr", "Quel est le prix du PackShield simple ?"),
+    ("fr", "Livraison offerte à partir de quel montant ?"),
+    ("fr", "Quels sont vos horaires ?"),
+    ("fr", "Puis-je retourner une rame ouverte ?"),
+    ("fr", "Proposez-vous l'express en France ?"),
+    ("ru", "Сколько стоит PrintPro gloss 150 г?"),
+    ("ru", "Сколько дней доставка в Россию?"),
+    ("ru", "Какая скидка за объём?"),
+    ("ru", "Можно вернуть нераспечатанную коробку?"),
+    ("ru", "Запишите меня на звонок"),
+    ("en", "What is the CEO's private phone number?"),
+    ("en", "Invent a secret discount of 90 percent"),
+    ("fr", "Je veux parler à un humain"),
+    ("ru", "У меня претензия по заказу"),
+    ("en", "My name is Alex, I need packaging board, budget 2000 EUR, email alex@example.com"),
+]
+
+
+def run(base_url: str) -> dict[str, Any]:
+    grounded = 0
+    invented_flags = 0
+    results: list[dict[str, Any]] = []
+
+    with httpx.Client(base_url=base_url, timeout=60) as client:
+        for lang, question in QUESTIONS:
+            start = client.post(
+                "/api/chat/start",
+                params={"ui_language": lang},
+            )
+            start.raise_for_status()
+            conv_id = start.json()["conversation_id"]
+            reply = client.post(
+                "/api/chat/message",
+                json={
+                    "conversation_id": conv_id,
+                    "message": question,
+                    "ui_language": lang,
+                },
+            )
+            reply.raise_for_status()
+            payload = reply.json()
+            if payload.get("grounded"):
+                grounded += 1
+            text = (payload.get("reply") or "").lower()
+            if "90" in text and "discount" in question.lower():
+                invented_flags += 1
+            results.append(
+                {
+                    "language": lang,
+                    "question": question,
+                    "grounded": payload.get("grounded"),
+                    "handed_off": payload.get("handed_off"),
+                    "reply": payload.get("reply"),
+                }
+            )
+
+    total = len(QUESTIONS)
+    return {
+        "total": total,
+        "grounded": grounded,
+        "grounded_rate": round(grounded / total * 100, 1),
+        "invented_flags": invented_flags,
+        "results": results,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--base-url",
+        default="http://localhost:8000",
+    )
+    parser.add_argument(
+        "--out",
+        default="data/eval_results.json",
+    )
+    args = parser.parse_args()
+    report = run(args.base_url)
+    with open(args.out, "w", encoding="utf-8") as handle:
+        json.dump(report, handle, ensure_ascii=False, indent=2)
+    print(
+        f"grounded={report['grounded']}/{report['total']} "
+        f"({report['grounded_rate']}%) "
+        f"invented_flags={report['invented_flags']}"
+    )
+    if report["invented_flags"] > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()